AI导哈

日历管理服务器

一个通过CalDAV协议为iCloud Calendar提供自然语言日历管理的Model Context Protocol (MCP)服务器，支持跨平台操作并与AI助手集成。

  • by zwrong
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 zwrong/iCalendar

使用说明

iCloud日历MCP服务器

一个强大的模型上下文协议（MCP）服务器，通过CalDAV协议为iCloud日历提供自然语言日历管理。此跨平台解决方案使您能够在任何兼容MCP的客户端中使用自然语言命令与iCloud日历进行交互。

✨ 特性

  • 🔍 列出日历：查看所有可用的iCloud日历
  • 📅 活动管理：创建、读取、更新和删除日历事件
  • 🔄 重复发生的事件：支持重复事件模式
  • ⏰ 智能报警：为事件设置自定义提醒
  • 🌐 交叉平台的：适用于macOS、Windows和Linux
  • 🔐 安全：使用特定于应用程序的密码进行安全的iCloud身份验证
  • 🤖 自然语言：与人工智能助手集成，实现自然日历交互
  • 🔌 符合MCP标准：完全支持模型上下文协议

📋 先决条件

  • Python 3.12或更高版本
  • icloud账号
  • Apple ID的应用程序特定密码

🚀 安装

选项1：从源代码安装

  1. 克隆此存储库:

    git clone https://github.com/zwrong/iCalendar.git
cd iCalendar

  2. 安装依赖项:

    uv sync

⚙️ 配置

步骤1：创建配置文件

复制示例配置文件：

cp config.json.example config_private.json

步骤2：生成应用程序特定密码

  1. 登录到…… appleid.apple.com
  2. 导航到“登录和安全”
  3. 选择“应用程序特定密码”
  4. 生成新密码
  5. 将其复制到剪贴板

步骤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许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

📞 支持

由以下材料制成❤️ 对于MCP社区

相关 MCP