iCloud日历MCP服务器
一个强大的模型上下文协议（MCP）服务器，通过CalDAV协议为iCloud日历提供自然语言日历管理。此跨平台解决方案使您能够在任何兼容MCP的客户端中使用自然语言命令与iCloud日历进行交互。
✨ 特性
- 🔍 列出日历：查看所有可用的iCloud日历
- 📅 活动管理：创建、读取、更新和删除日历事件
- 🔄 重复发生的事件：支持重复事件模式
- ⏰ 智能报警：为事件设置自定义提醒
- 🌐 交叉平台的：适用于macOS、Windows和Linux
- 🔐 安全：使用特定于应用程序的密码进行安全的iCloud身份验证
- 🤖 自然语言：与人工智能助手集成，实现自然日历交互
- 🔌 符合MCP标准：完全支持模型上下文协议
📋 先决条件
- Python 3.12或更高版本
- icloud账号
- Apple ID的应用程序特定密码
🚀 安装
选项1：从源代码安装
- 克隆此存储库:
git clone https://github.com/zwrong/iCalendar.git
cd iCalendar- 安装依赖项:
uv sync⚙️ 配置
步骤1：创建配置文件
复制示例配置文件：
cp config.json.example config_private.json步骤2：生成应用程序特定密码
- 登录到…… appleid.apple.com
- 导航到“登录和安全”
- 选择“应用程序特定密码”
- 生成新密码
- 将其复制到剪贴板
步骤3：配置凭据
编辑 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桌面配置
添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"iCalendar": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/iCalendar",
"run",
"mcp-ical"
]
}
}
}故障排除
如果遇到“spawn uv ENOENT”错误：
当系统找不到 uv PATH中的命令。要解决此问题，请指定您的 uv 可执行文件：
{
"mcpServers": {
"ical": {
"command": "/ABSOLUTE/PATH/TO/uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/iCalendar",
"run",
"mcp-ical"
]
}
}
}找到通往你的道路 uv 可通过运行以下命令执行：
which uv
# or on Windows:
where uv替换 /ABSOLUTE/PATH/TO/uv 命令返回的实际路径。
配置完Claude Desktop后，重新启动Claude Desktop并使用它！
📚 用法示例
示例1：检查你的计划
User: "Do I have any plans today?"
AI: I'll check your calendar for today
→ list_events("2025-11-06T00:00:00", "2025-11-06T23:59:59")示例2：创建事件
User: "Schedule a lunch meeting with John on Friday at noon"
AI: I'll create that event for you
→ create_event({
"title": "Lunch Meeting with John",
"start_datetime": "2025-01-17T12:00:00",
"end_datetime": "2025-01-17T13:00:00",
"calendar_name": "Personal",
"description": "Discuss project updates"
})示例3：删除事件
User: "Delete the lunch meeting this week"
AI: I'll create that event for you
→ create_event({
"title": "Lunch Meeting with John",
"start_datetime": "2025-01-17T12:00:00",
"end_datetime": "2025-01-17T13:00:00",
"calendar_name": "Personal",
"description": "Discuss project updates"
})示例4：设置提醒
User: "Remind me about the presentation tomorrow at 9 AM, set the reminder for 30 minutes before"
AI: I'll create the event with a 30-minute reminder
→ create_event({
"title": "Presentation",
"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：CalendarManager包装器提供兼容层models.py：用于请求/响应验证的Pydantic模型config.py：具有优先级处理的配置管理
依赖项
- mcp\[cli\]：模型上下文协议框架
- 卡尔达夫：用于iCloud访问的CalDAV客户端库
- vobject：iCalendar文件格式解析
- 请求：：用于CalDAV操作的HTTP客户端
- 日志记录器：结构化日志记录
- 皮丹提克：数据验证和序列化
🤝 与AI客户端集成
此MCP服务器可与任何兼容MCP的客户端配合使用，包括：
- 克劳德桌面
- 克劳德代码
- 自定义MCP客户端
🐛 故障排除
身份验证问题
- 验证您的Apple ID电子邮件是否正确
- 确保您使用的是特定于应用程序的密码（而不是常规密码）
- 检查应用程序特定密码是否未过期
- 如果需要，请确认您的Apple ID已启用2FA
连接问题
- 验证您的互联网连接
- 检查您的Apple ID设置中是否启用了iCloud日历
- 确保防火墙允许出站HTTPS连接
事件创建/更新失败
- 验证事件时间是否为ISO格式（YYYY-MM-DDTHH:MM:SS）
- 确保开始时间早于结束时间
- 检查日历名称是否存在
📝 发展
项目结构
mcp-ical/
├── src/
│ └── mcp_ical/
│ ├── server.py # MCP server entry point
│ ├── caldav_client.py # CalDAV operations
│ ├── ical.py # Calendar manager wrapper
│ ├── models.py # Data models
│ └── config.py # Configuration
├── tests/ # Test suite
├── config.json.example # Configuration template
├── pyproject.toml # Project metadata
└── README.md # This file📖 已知问题和解决方案
最近修复（v0.1.0）
- 固定的:
update_event和delete_event现在可以正确处理URL编码的事件ID - 固定的：事件标识现在检查两者
event.id和event.url属性 - 固定的：事件数据的稳健类型检查（字符串vs vobject）
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🙏 致谢
📞 支持
- 📧 电子邮件：zwrong@me.com
- 🐛 问题：
- 💬 讨论：
______________________________________________________________________
由以下材料制成❤️ 对于MCP社区