项目简介

iCloud CalDAV MCP 连接器是一个HTTP MCP服务器，它将iCloud日历（CalDAV）功能封装为一系列工具，使得支持MCP协议的客户端（如ChatGPT自定义连接器、IDE等）可以通过这些工具管理iCloud日历。它允许用户使用Apple ID和iCloud应用专用密码，安全地列出日历、读取事件以及创建、更新和删除事件。

主要功能点

列出日历: 获取用户所有可用日历的名称和URL。
列出事件: 在指定日历和时间范围内查找事件，支持展开重复事件。
创建事件: 在指定日历中创建新事件，包括摘要、开始时间、结束时间、时区和描述。
更新事件: 修改现有事件的摘要、时间、时区和描述（对重复事件更新整个系列）。
删除事件: 从日历中删除指定事件。
健康检查: 提供 '/health' 端点用于服务器状态检查。
深度研究模式 (可选): 启用只读模式，提供 'search' 和 'fetch' 工具，用于在日历事件中进行文本搜索和获取原始ICS内容。

安装步骤

Python环境: 确保您的系统安装了 Python 3.11 或更高版本。

克隆仓库:

git clone https://github.com/localhost433/icloud-mcp.git
cd icloud-mcp

创建虚拟环境:

python -m venv .venv

激活虚拟环境:

macOS/Linux:

source .venv/bin/activate

Windows:

.venv\Scripts\activate

安装依赖: 项目仓库中未提供 'requirements.txt' 文件，您需要手动安装依赖。根据 'server.py' 文件，主要依赖项包括 'fastmcp' 和 'caldav'。
```
pip install fastmcp caldav python-dotenv icalendar
```

配置环境变量: 在 'icloud-mcp' 仓库的根目录下，即 'server.py' 文件同级目录，创建 '.env' 文件，并填写以下内容：

[email protected]         # 您的Apple ID邮箱（必须是邮箱地址，而非电话号码）
ICLOUD_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx    # 您的iCloud应用专用密码
CALDAV_URL=https://caldav.icloud.com       # (可选) CalDAV服务器URL，默认已提供
HOST=127.0.0.1                             # (可选) 服务器监听地址，默认本地
PORT=8000                                  # (可选) 服务器监听端口，默认8000
TZID=America/New_York                      # (可选) 新建/编辑事件的默认时区（IANA格式，如 Asia/Shanghai）

# 深度研究模式配置 (可选)
DR_PROFILE=0                               # 设为1启用只读深度研究模式 (默认0)
SCAN_DAYS=1095                             # DR模式下搜索/获取事件的时间窗口 (天，默认约3年)

注意: 'APPLE_ID' 和 'ICLOUD_APP_PASSWORD' 是必填项。iCloud应用专用密码可以在Apple ID账户页面生成。

服务器配置

此MCP服务器需要作为MCP客户端的后端服务启动。MCP客户端通常会通过如下 JSON 配置来连接和启动服务器：

{
  "serverName": "icloud-caldav",
  "command": ["python", "server.py"],
  "args": [],
  "env": {
    "APPLE_ID": "[email protected]",             // 您的Apple ID邮箱
    "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx",        // 您的iCloud应用专用密码
    "TZID": "America/New_York",                         // 新建/编辑事件的默认时区
    "HOST": "127.0.0.1",                                // 服务器监听地址 (默认127.0.0.1)
    "PORT": "8000"                                      // 服务器监听端口 (默认8000)
    // 其他可选环境变量如 CALDAV_URL, DR_PROFILE, SCAN_DAYS 也可在此配置
  },
  "transport": "http",                                  // 传输协议
  "path": "/mcp",                                       // MCP接口路径
  "url": "http://127.0.0.1:8000/mcp"                    // MCP服务器的完整URL，供客户端连接
}

重要提示: 在生产环境中，'HOST' 和 'PORT' 应根据实际部署调整，并且通常需要通过公共 HTTPS 端点（如 Cloudflare Tunnel、ngrok 或 VPS + Caddy/Nginx）对外暴露。出于安全考虑，请务必对服务添加认证或访问控制。

基本使用方法

启动服务器: 确保 '.env' 文件已配置，然后在激活的虚拟环境中运行：

python server.py
# 服务器将监听 http://127.0.0.1:8000

健康检查: 在浏览器或命令行工具中访问 '/health' 端点以确认服务器正常运行：

curl http://127.0.0.1:8000/health
# 应返回 "OK"

连接MCP客户端: 使用支持MCP协议的客户端（如 'fastmcp' 客户端或 ChatGPT 自定义连接器），配置其连接到 'http://127.0.0.1:8000/mcp' 端点，即可调用服务器暴露的工具来管理iCloud日历。例如，使用 Python 'fastmcp' 客户端调用 'list_calendars' 工具：

import asyncio
from fastmcp import Client

async def main():
    async with Client("http://127.0.0.1:8000/mcp") as c:
        # 调用list_calendars工具
        calendars = await c.call_tool("list_calendars")
        print("可用日历:", calendars)

        # 示例：创建一个新事件 (请替换为您的日历URL)
        # cal_url = "<您的一个日历URL>"
        # uid = await c.call_tool("create_event", {
        #     "calendar_name_or_url": cal_url,
        #     "summary":"MCP Demo Event",
        #     "start":"2025-09-29T10:00:00",
        #     "end":"2025-09-29T11:00:00",
        #     "tzid":"America/New_York"
        # })
        # print("创建事件UID:", uid)

asyncio.run(main())

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息