项目介绍
iCloud日历MCP服务器
这是一个强大的模型上下文协议（MCP）服务器，通过CalDAV协议为iCloud日历提供自然语言的日历管理功能。这个跨平台解决方案使您能够使用任何MCP兼容客户端中的自然语言命令与您的iCloud日历进行交互。
✨ 特性
- 🔍 列出日历：查看所有可用的iCloud日历
- 📅 事件管理：创建、读取、更新和删除日历事件
- 🔄 重复事件：支持重复事件模式
- ⏰ 智能提醒：为事件设置自定义提醒
- 🌐 跨平台：适用于macOS、Windows和Linux
- 🔐 安全：使用应用专用密码进行安全的iCloud身份验证
- 🤖 自然语言：与AI助手集成，实现自然的日历交互
- 🔌 MCP兼容：完全支持模型上下文协议
📋 先决条件
- Python 3.12或更高版本
- 一个iCloud账户
- 用于Apple ID的应用专用密码
🚀 安装
方案1：从源码安装
-
克隆此仓库：
git clone https://github.com/zwrong/iCalendar.git cd iCalendar -
安装依赖项：
uv sync
⚙️ 配置
第一步：创建配置文件
复制示例配置文件：
cp config.json.example config_private.json
第二步：生成应用专用密码
- 登录到 appleid.apple.com
- 导航到“登录与安全性”
- 选择“应用专用密码”
- 生成一个新的密码
- 将其复制到剪贴板
第三步：配置凭据
编辑 config_private.json：
{
"caldav": {
"server_url": "https://caldav.icloud.com/",
"username": "your_apple_id@icloud.com",
"password": "your_app_specific_password"
}
}
重要：不要将 config_private.json 提交到版本控制系统！它包含敏感凭证。
🏃 运行服务器
启动服务器：
uv run mcp-ical
在使用MCP客户端中的iCalendar时，请勿关闭正在运行服务器的终端。
Claude Desktop配置
添加到您的 claude_desktop_config.json：
{
"mcpServers": {
"iCalendar": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/iCalendar",
"run",
"mcp-ical"
]
}
}
}
故障排除
如果遇到“spawn uv ENOENT”错误：
当系统无法在PATH中找到uv命令时会出现此错误。要解决此问题，请指定uv可执行文件的完整路径：
{
"mcpServers": {
"ical": {
"command": "/ABSOLUTE/PATH/TO/uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/iCalendar",
"run",
"mcp-ical"
]
}
}
}
通过运行以下命令找到uv可执行文件的路径：
which uv
# 或在Windows上：
where uv
用实际返回的路径替换 /ABSOLUTE/PATH/TO/uv。
配置Claude Desktop后，重启Claude Desktop并使用它！
📚 使用示例
示例1：检查您的计划
用户："今天我有计划吗？"
AI：我将为您检查今天的日程安排
→ list_events("2025-11-06T00:00:00", "2025-11-06T23:59:59")
示例2：创建事件
用户："周五中午与John安排午餐会议"
AI：我将为您创建该事件
→ create_event({
"title": "与John的午餐会议",
"start_datetime": "2025-01-17T12:00:00",
"end_datetime": "2025-01-17T13:00:00",
"calendar_name": "个人",
"description": "讨论项目更新"
})
示例3：删除事件
用户："删除本周的午餐会议"
AI：我将为您创建该事件
→ create_event({
"title": "与John的午餐会议",
"start_datetime": "2025-01-17T12:00:00",
"end_datetime": "2025-01-17T13:00:00",
"calendar_name": "个人",
"description": "讨论项目更新"
})
示例4：设置提醒
用户："明天早上9点提醒我关于演讲，提前30分钟提醒"
AI：我将为您创建带有30分钟提醒的事件
→ create_event({
"title": "演讲",
"start_datetime": "2025-01-06T09:00:00",
"end_datetime": "2025-01-06T10:00:00",
"alarm": 30
})
🏗️ 架构
核心组件
server.py：使用FastMCP定义工具的MCP服务器入口点caldav_client.py：用于iCloud CalDAV访问和CRUD操作的CalDAVManager类ical.py：提供兼容层的日历管理器包装器models.py：用于请求/响应验证的Pydantic模型config.py：具有优先级处理的配置管理
依赖项
- mcp[cli]：模型上下文协议框架
- caldav：用于iCloud访问的CalDAV客户端库
- vobject：iCalendar文件格式解析
- requests：用于CalDAV操作的HTTP客户端
- loguru：结构化日志记录
- pydantic：数据验证和序列化
🤝 与AI客户端的集成
此MCP服务器与任何MCP兼容客户端一起工作，包括：
- Claude Desktop
- Claude Code
- 自定义MCP客户端
🐛 故障排除
认证问题
- 验证您的Apple ID电子邮件是否正确
- 确保您使用的是应用专用密码（而不是常规密码）
- 检查应用专用密码是否未过期
- 如果需要，确认Apple ID启用了两步验证
连接问题
- 验证您的互联网连接
- 检查iCloud日历是否在您的Apple ID设置中启用
- 确保防火墙允许HTTPS出站连接
事件创建/更新失败
- 验证事件时间是否为ISO格式（YYYY-MM-DDTHH:MM:SS）
- 确保开始时间早于结束时间
- 检查日历名称是否存在
📝 开发
项目结构
mcp-ical/
├── src/
│ └── mcp_ical/
│ ├── server.py # MCP服务器入口点
│ ├── caldav_client.py # CalDAV操作
│ ├── ical.py # 日历管理器包装器
│ ├── models.py # 数据模型
│ └── config.py # 配置
├── tests/ # 测试套件
├── config.json.example # 配置模板
├── pyproject.toml # 项目元数据
└── README.md # 此文件
📖 已知问题及解决方案
最近修复（v0.1.0）
- 修复：
update_event和delete_event现在正确处理了URL编码的事件ID - 修复：事件识别现在检查了
event.id和event.url属性 - 修复：对事件数据进行了健壮的类型检查（字符串 vs vobject）
📄 许可证
本项目根据MIT许可证发布 - 查看LICENSE文件以获取详细信息。
🙏 致谢
📞 支持
- 📧 邮件：zwrong@me.com
- 🐛 问题：GitHub Issues
- 💬 讨论：GitHub Discussions
为MCP社区制作 ❤️