iCloud日历管理服务

iCloud日历MCP服务器

A. 模型上下文协议 该服务器允许AI助手通过CalDAV完全访问Apple iCloud日历。列出日历、搜索事件、创建、更新和删除事件——所有这些都来自Claude或任何兼容MCP的客户端。

用Go和the mcp-go SDK。作为Linux、macOS和Windows的单个静态二进制文件发布。

目录

• 特性
• 快速开始
• 先决条件
• 安装
• 配置
• 使用Claude Desktop
• 可用工具
• 发展
• 建筑
• 安全
• 故障排除
• 贡献
• 许可证

特性

日历操作

• 列出所有iCloud日历，包括路径、名称、描述和颜色
• 使用日期范围过滤器和分页搜索事件
• 创建包含标题、时间、描述、位置和与会者的事件
• 更新现有事件上的单个字段（使用指针字段进行部分更新）
• 永久删除事件

定期活动和与会者

• 将重复事件（RRULE）扩展为日期范围内的单个事件
• 使用角色（主席、需求参与者、操作员）和状态管理与会者

多账户支持

• 从单个服务器实例管理多个iCloud帐户
• 通过配置 ACCOUNTS_FILE JSON或单账户环境变量
• 每个帐户的速率限制和重试逻辑

可操作的

• 具有UUID请求相关性的结构化JSON日志记录
• 每次工具调用时可配置超时中间件（默认25秒）
• 针对瞬态故障，采用指数回退自动重试
• 限制每个帐户的速率以避免iCloud限制
• 健康终点(/healthz, /readyz)普罗米修斯指标(/metrics)
• 变异操作的审计日志记录（无PII）
• 所有工具参数的输入验证
• 用于客户端安全的MCP工具注释（只读、破坏性、幂等）
• SIGTERM/SIGINT上的优雅关机
• 为企业部署提供mTLS和自定义CA支持
• file:// Docker/Kubernetes机密的凭据加载
• 具有测试、linting和漏洞扫描的CI管道

快速开始

# Install
go install github.com/rgabriel/mcp-icloud-calendar@latest

# Set credentials (app-specific password, not your main iCloud password)
export ICLOUD_EMAIL="you@icloud.com"
export ICLOUD_PASSWORD="xxxx-xxxx-xxxx-xxxx"

# Run
mcp-icloud-calendar

或者从以下网址下载预构建的二进制文件 发布 页面。

先决条件

• 转到1.21+ -- 安装 （仅在从源构建时需要）
• Icloud帐户 启用了双因素身份验证
• 应用程序特定密码 --CalDAV访问所需

生成特定于应用程序的密码

1. 首选 appleid.apple.com 并登录
2. 导航到 登录和安全 > 应用程序特定密码
3. 点击 生成特定于应用程序的密码
4. 输入标签（例如“MCP日历服务器”）并单击 创建
5. 复制生成的密码(xxxx-xxxx-xxxx-xxxx)并安全地存放

笔记：

• 您的Apple ID必须启用双因素身份验证
• 您最多可以创建25个活动应用程序特定密码
• 更改您的主Apple ID密码会撤销所有特定于应用程序的密码
• 切勿使用您的主iCloud密码访问CalDAV

安装

来源

git clone https://github.com/rgabriel/mcp-icloud-calendar.git
cd mcp-icloud-calendar
make build

使用 go install

go install github.com/rgabriel/mcp-icloud-calendar@latest

码头工人

docker build -t mcp-icloud-calendar .

docker run \
  -e ICLOUD_EMAIL="you@icloud.com" \
  -e ICLOUD_PASSWORD="xxxx-xxxx-xxxx-xxxx" \
  mcp-icloud-calendar

Docker镜像使用多阶段构建 无发行版 基本映像，并以非root用户身份运行。

预构建二进制文件

从以下网址下载适用于您平台的二进制文件 发布 页面。二进制文件可用于：

SHA256校验和与每个二进制一起提供。

配置

单一账户

服务器至少需要两个环境变量：

您可以将这些设置为环境变量，也可以将它们放置在 .env 文件：

cp .env.example .env
# Edit .env with your credentials

凭据支持 file:// Docker/Kubernetes秘密的前缀（例如。， ICLOUD_PASSWORD=file:///run/secrets/password).

多账户

要管理多个iCloud帐户，请设置 ACCOUNTS_FILE 指向JSON文件的环境变量：

{
  "accounts": [
    {
      "name": "personal",
      "email": "personal@icloud.com",
      "password": "xxxx-xxxx-xxxx-xxxx",
      "calendarId": "/1234567/calendars/home/"
    },
    {
      "name": "work",
      "email": "work@icloud.com",
      "password": "yyyy-yyyy-yyyy-yyyy"
    }
  ]
}

每个工具都接受一个可选 account 参数。省略它以使用默认帐户。

使用Claude Desktop

将服务器添加到Claude Desktop配置文件中。

macOS -- ~/Library/Application Support/Claude/claude_desktop_config.json

Linux -- ~/.config/claude/claude_desktop_config.json

视窗 -- %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "/path/to/mcp-icloud-calendar",
      "env": {
        "ICLOUD_EMAIL": "you@icloud.com",
        "ICLOUD_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

保存后重新启动Claude Desktop。

可用工具

服务器公开了5个MCP工具。每个工具都包含模式约束和注释，指示它是只读的、破坏性的还是幂等的。

列表_日历

列出所有可用的iCloud日历。返回每个日历的路径、显示名称、描述和颜色。先调用此命令以发现有效 calendarId 价值观。

搜索事件

在日期范围内搜索日历事件。返回带有事件详细信息（包括重复信息和与会者）的分页结果。

create_event

创建新的日历事件。返回创建的事件的唯一ID。

与会者格式：

[
  {"email": "alice@example.com", "name": "Alice", "role": "REQ-PARTICIPANT"},
  {"email": "bob@example.com", "name": "Bob", "role": "OPT-PARTICIPANT", "status": "TENTATIVE"}
]

支持的角色： CHAIR, REQ-PARTICIPANT, OPT-PARTICIPANT支持的状态： NEEDS-ACTION, ACCEPTED, DECLINED, TENTATIVE.

update_事件

更新现有事件的特定字段。仅包含要更改的字段，省略的字段保持不变。

删除事件

永久删除日历事件。此操作无法撤消。

发展

建筑

make build          # Build binary with version embedding
make test           # Run tests with race detector
make lint           # Run golangci-lint
make clean          # Remove build artifacts
make docker         # Build Docker image
make run            # Build and run

本地运行

export ICLOUD_EMAIL="you@icloud.com"
export ICLOUD_PASSWORD="xxxx-xxxx-xxxx-xxxx"
make run

测试

该项目包括14个测试文件中的88个表驱动测试，涵盖了所有工具处理程序、CalDAV客户端逻辑、输入验证、重试/速率限制包装器、重复扩展、参与者解析和错误路径。测试使用模拟实现 CalendarService 接口——不需要实时CalDAV连接。

make test

MCP检验员测试

使用 MCP检查员 以交互方式测试服务器：

npx @modelcontextprotocol/inspector mcp-icloud-calendar

CI管道

每一次推动 main 或 dev 每个pull请求都会运行：

• go vet 和 go test -race --正确性和数据竞争检测
• golangci-lint --静态分析（errcheck、govet、staticcheck、gosec、gocritic等）
• govulncheck --已知漏洞扫描

标签发布(v*.*.*)使用SHA256校验和触发自动跨平台构建。

建筑

mcp-icloud-calendar/
  main.go                Server setup, multi-account init, tool registration, middleware chain
  config/
    config.go            Environment variable loading, validation, file:// credential support
    accounts.go          Multi-account JSON configuration
  caldav/
    interface.go         CalendarService interface
    client.go            CalDAV client (caldav.icloud.com, TLS/mTLS)
    retry.go             Retry wrapper with exponential backoff
    ratelimit.go         Rate-limiting wrapper (token bucket)
    recurrence.go        RRULE expansion for recurring events
    attendees.go         Attendee parsing and serialization
    validation.go        Input validation for CalDAV parameters
  tools/
    accounts.go          AccountClients multi-account resolver
    list_calendars.go    list_calendars handler
    search_events.go     search_events handler
    create_event.go      create_event handler
    update_event.go      update_event handler
    delete_event.go      delete_event handler
  health/server.go       Health check and readiness endpoints
  metrics/               Prometheus metrics and tool call middleware
  middleware/             Request ID middleware (UUID correlation)
  logging/               Structured JSON logging (slog)

客户链： 每个帐户都有自己的管道： realClient -> RateLimitedClient -> RetryClient

中间件链： 每个工具调用都经过 RequestID -> Timeout -> Metrics -> handler请求ID中间件为日志关联分配UUID。超时中间件强制执行可配置的截止日期。度量中间件记录工具调用持续时间和结果。

审核日志记录： 诱变操作(create_event, update_event, delete_event)通过调用后挂钩记录工具名称、帐户、日历ID和状态，不包括PII（标题、描述、位置）。

依赖项

安全

• 仅限应用程序特定密码 --从不接受或存储您的主iCloud密码
• TLS无处不在 --所有CalDAV通信都使用HTTPS和TLS验证
• mTLS支持 --企业环境的可选客户端证书身份验证
• 输入验证 --所有刀具参数的类型、范围和格式都经过验证
• 大小和格式限制 --通过MCP模式强制的标题长度、时间范围和参数约束
• 凭据文件加载 -- file:// 安全秘密注入前缀（Docker、Kubernetes）
• 分散Docker镜像 --最小攻击面，以非根模式运行
• 无第三方数据共享 --服务器在本地运行，仅与iCloud服务器通信
• 可撤销访问 --可以随时从appleid.apple.com撤销特定于应用程序的密码
• 审计跟踪 --出于合规性考虑，在没有PII的情况下记录变异操作

永远不要承诺你的 .env 文件到版本控制。这 .gitignore 已经将其排除在外。

故障排除

认证失败

• 验证您使用的是特定于应用程序的密码，而不是iCloud主密码
• 检查您的Apple ID是否启用了双因素身份验证
• 在appleid.apple.com重新生成新的应用程序特定密码
• 确认您的电子邮件地址与您的Apple ID匹配

未找到日历

• 跑 list_calendars 查看您帐户的确切日历路径
• 日历路径看起来像 /1234567/calendars/home/ --总是从开始 /
• 确保您正在使用 path 价值来自 list_calendars，不是显示名称

日期格式无效

• 使用RFC 3339/ISO 8601： 2025-01-15T14:30:00Z
• 如果不是UTC，请包括时区偏移： 2025-01-15T14:30:00-05:00

超时或响应缓慢

• 检查您的互联网连接
• 减少 limit 大型结果集的参数
• 使用较窄的日期范围 startTime/endTime
• 增加 TOOL_TIMEOUT 如果您的网络速度较慢（默认值：25秒）

重复事件未扩展

• 集 expandRecurrence 到 true 在 search_events
• 两者 startTime 和 endTime 必须为重复扩展提供
• 扩展仅在指定日期范围内有效

未找到事件

• 验证事件ID是否与来自的UID匹配 search_events
• 确保您使用的是正确的 calendarId
• 自检索ID以来，该事件可能已被删除或移动

贡献

欢迎捐款。请在提交pull请求之前打开一个问题来讨论更大的更改。

许可证

MIT许可证——见 许可证 了解详情。