日历管理服务器

iCloud日历MCP服务器（本地）

本地MCP服务器 它在您的计算机上运行，通过CalDAV协议提供iCloud日历集成。您的MCP客户端（Claude Desktop等）在后台自动管理服务器，无需手动执行。

允许本地安装的LLM桌面应用程序（如Claude desktop）使用精细的每个日历权限管理日历事件，同时将凭据完全保留在本地。

⚠️ 免责声明

这是一个 非官方的第三方开源工具确实如此 不隶属于、不受苹果股份有限公司背书或赞助。

该工具使用标准CalDAV协议（RFC 4791）通过苹果公开记录的CalDAV端点访问日历数据。iCloud和Apple Calendar是Apple股份有限公司在美国和其他国家/地区注册的商标。

特性

• 在您的计算机上本地运行 通过MCP客户端进行自动生命周期管理
• 完全隐私：凭据和数据永远不会离开您的计算机
• 每个日历的读/写权限控制
• 列出日历，获取/搜索/创建/更新/删除事件
• 自动过滤提醒/任务日历（VTODO）
• JSON和Markdown输出格式
• CalDAV协议，具有特定于应用程序的密码身份验证
• 连接池（30分钟客户端重用）
• 多层缓存：日历（5分钟TTL）、事件UID（60秒TTL，1000个条目）、日期时间格式（100种模式）
• 通过asyncio进行并发日历操作
• 速率限制（5个请求/秒）

运作原理

这是一个 本地MCP服务器 它完全在您的机器上运行：

1. 配置一次：将服务器路径和凭据添加到MCP客户端配置中（例如，Claude Desktop）
2. 自动执行：需要时，您的MCP客户端会在后台自动启动服务器进程
3. 直接连接：服务器直接从您的计算机连接到iCloud，不涉及第三方服务器
4. 完全隐私：您的iCloud凭据和日历数据永远不会离开您的计算机

您永远不需要手动运行服务器--只需配置它，您的MCP客户端就可以处理一切。

需求

• Python 3.8+
• 具有双重身份验证的iCloud帐户
• 应用程序特定密码（不是您的主iCloud密码）
• MCP兼容客户端

安装

# Clone repository
git clone https://github.com/bjorn-t/icloud-calendar-mcp.git
cd icloud-calendar-mcp

# Install dependencies
pip install -r requirements.txt

快速开始

1.生成应用程序特定密码

1. 首选https://appleid.apple.com
2. 登录并导航到安全→ 应用程序特定密码
3. 生成新密码
4. 保存16个字符的密码（格式： xxxx-xxxx-xxxx-xxxx)

2.配置您的MCP客户端（就是这样！）

使用您的凭据将服务器添加到MCP客户端配置中。 客户端将在后台自动运行服务器--您不需要手动执行任何操作。

Claude桌面版 （macOS： ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "python3",
      "args": ["/absolute/path/to/icloud_calendar_mcp.py"],
      "env": {
        "ICLOUD_USERNAME": "your@email.com",
        "ICLOUD_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

其他MCP客户端:

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "python3",
      "args": ["/path/to/icloud_calendar_mcp.py"],
      "env": {
        "ICLOUD_USERNAME": "your@email.com",
        "ICLOUD_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

就是这样！ 重新启动MCP客户端，服务器将在需要时在后台自动运行。您已准备好使用日历工具。

3.权限配置（可选）

默认：所有日历均以以下方式开始 只读的首次使用时没有提示。

要授予写入权限（创建/更新/删除事件）：

1. 查找您的日历名称：让你的法学硕士跑 icloud_list_calendars
2. 编辑权限文件：创建/编辑 ~/.icloud_calendar_permissions.json:

{
  "Work": {
    "read": true,
    "write": true
  },
  "Personal": {
    "read": true,
    "write": false
  }
}

3. 重新启动MCP客户端 应用更改

或者，使用 icloud_set_calendar_permissions LLM中的工具。

可用工具

安全

写入操作在执行前验证权限。权限持续存在 ~/.icloud_calendar_permissions.json默认值：新日历只读。

使用特定于应用程序的密码（不是iCloud主密码）。切勿将凭据提交到版本控制。

技术细节

• 协议：CalDAV（RFC 4791）通过 python-caldav
• 服务器: https://caldav.icloud.com/
• 格式：iCalendar（RFC 5545）
• 局限性：不支持OAuth、webhooks或PATCH。更新需要完整的PUT。
• 演出：25K字符响应限制，每个查询50-250个事件
• 缓存：日历缓存（5分钟TTL）、事件UIDCache（60秒TTL，最大1000）、客户端池（30分钟TTL）
• 并发：使用线程池委派的异步操作，速率限制为5请求/秒

发展

对于正常使用，您不需要手动运行服务器--您的MCP客户端会自动执行此操作。

对于独立测试和开发：

1. 创建一个 .env 使用您的凭据文件（请参阅 .env.example)
2. 直接运行： python3 icloud_calendar_mcp.py

这只需要用于调试、测试更改或在MCP客户端之外使用服务器。

贡献

欢迎发布问题和PR。包括错误消息、Python版本和操作系统错误。

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

版权所有（c）2025比约恩·索尔德布兰德

商标通知

iCloud和Apple Calendar是Apple股份有限公司的商标。此项目使用开放的CalDAV标准，不隶属于Apple股份有限公司。

致谢

• 蟒蛇caldav -CalDAV客户端库
• 模型上下文协议 -MCP规范
• 伊肯达尔 -iCalendar解析