JinDaGe - che-ical-mcp MCP Details

article

README

🚀 che-ical-mcp

che-ical-mcp 是一款适用于 macOS 的日历与提醒事项 MCP 服务器，它通过原生的 EventKit 集成，为用户提供了全面的日历和任务管理功能。

English | 繁體中文

🚀 快速开始

针对 Claude Desktop

选项 A：MCPB 一键安装（推荐）

从 Releases 下载最新的 .mcpb 文件，然后双击安装。

选项 B：手动配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json 文件：

{
  "mcpServers": {
    "che-ical-mcp": {
      "command": "/usr/local/bin/che-ical-mcp"
    }
  }
}

针对 Claude Code (CLI)

# 若需要，创建 ~/bin 目录
mkdir -p ~/bin

# 下载最新版本
curl -L https://github.com/kiki830621/che-ical-mcp/releases/latest/download/CheICalMCP -o ~/bin/CheICalMCP
chmod +x ~/bin/CheICalMCP

# 添加到 Claude Code
# --scope user    : 可在所有项目中使用（存储在 ~/.claude.json 中）
# --transport stdio: 通过 stdin/stdout 进行本地二进制执行
# --              : Claude 选项和命令之间的分隔符
claude mcp add --scope user --transport stdio che-ical-mcp -- ~/bin/CheICalMCP

💡 使用建议：始终将二进制文件安装到本地目录，如 ~/bin/。避免将其放置在云同步文件夹（Dropbox、iCloud、OneDrive）中，因为文件同步操作可能会导致 MCP 连接超时。

从源代码构建（可选）

git clone https://github.com/kiki830621/che-ical-mcp.git
cd che-ical-mcp
swift build -c release

首次使用时，macOS 会提示请求日历和 提醒事项 的访问权限，请点击“允许”。

✨ 主要特性

| 特性 | 其他日历 MCP | che-ical-mcp | |---------|---------------------|--------------| | 日历事件 | 支持 | 支持 | | 提醒事项/任务 | 不支持 | 支持 | | 提醒事项 #标签 | 不支持 | 支持（MCP 级别） | | 多关键字搜索 | 不支持 | 支持 | | 重复检测 | 不支持 | 支持 | | 冲突检测 | 不支持 | 支持 | | 批量操作 | 不支持 | 支持 | | 本地时区 | 不支持 | 支持 | | 来源区分 | 不支持 | 支持 | | 创建日历 | 部分支持 | 支持 | | 删除日历 | 部分支持 | 支持 | | 事件提醒 | 部分支持 | 支持 | | 位置与 URL | 部分支持 | 支持 | | 开发语言 | Python | Swift（原生） |

📦 安装指南

安装要求

macOS 13.0 或更高版本
Xcode 命令行工具（仅在从源代码构建时需要）

针对 Claude Desktop

方法 1：MCPB 一键安装（推荐）

从 Releases 下载 che-ical-mcp.mcpb 文件。
双击 .mcpb 文件进行安装。
重启 Claude Desktop。

方法 2：手动配置

下载二进制文件：

curl -L https://github.com/kiki830621/che-ical-mcp/releases/latest/download/CheICalMCP -o /usr/local/bin/che-ical-mcp
chmod +x /usr/local/bin/che-ical-mcp

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json 文件：

{
  "mcpServers": {
    "che-ical-mcp": {
      "command": "/usr/local/bin/che-ical-mcp"
    }
  }
}

重启 Claude Desktop。

针对 Claude Code (CLI)

# 若需要，创建 ~/bin 目录
mkdir -p ~/bin

# 下载二进制文件
curl -L https://github.com/kiki830621/che-ical-mcp/releases/latest/download/CheICalMCP -o ~/bin/CheICalMCP
chmod +x ~/bin/CheICalMCP

# 向 Claude Code 注册（用户范围 = 可在所有项目中使用）
claude mcp add --scope user --transport stdio che-ical-mcp -- ~/bin/CheICalMCP

从源代码构建（可选）

git clone https://github.com/kiki830621/che-ical-mcp.git
cd che-ical-mcp
swift build -c release

# 复制到 ~/bin 并注册
cp .build/release/CheICalMCP ~/bin/
claude mcp add --scope user --transport stdio che-ical-mcp -- ~/bin/CheICalMCP

授予权限

首次使用时，macOS 会提示请求日历和 提醒事项 的访问权限，请点击“允许”。

⚠️ 重要提示

macOS Sequoia (15.x) 注意事项：权限对话框归因于启动 MCP 服务器的 父应用程序，而不是二进制文件本身。这意味着：

| 环境 | 权限归因于 | |-------------|------------------------| | Claude Desktop | Claude Desktop.app ✅（自动生效） | | 在 Terminal.app 中使用 Claude Code | Terminal.app ✅（自动生效） | | 在 VS Code 中使用 Claude Code | VS Code ❌（可能不显示对话框） | | 在 iTerm2 中使用 Claude Code | iTerm2 ✅（自动生效） |

如果权限对话框未出现（常见于 VS Code），你需要在 VS Code 的 Info.plist 中添加 NSCalendarsFullAccessUsageDescription：
# 向 VS Code 添加日历使用说明
/usr/libexec/PlistBuddy -c "Add :NSCalendarsFullAccessUsageDescription string 'VS Code needs calendar access for MCP extensions.'" \
  "/Applications/Visual Studio Code.app/Contents/Info.plist"
/usr/libexec/PlistBuddy -c "Add :NSRemindersFullAccessUsageDescription string 'VS Code needs reminders access for MCP extensions.'" \
  "/Applications/Visual Studio Code.app/Contents/Info.plist"

# 重新签名 VS Code（修改 Info.plist 后需要）
codesign -s - -f --deep "/Applications/Visual Studio Code.app"

# 重启 VS Code，权限对话框将出现
注意：此修改在 VS Code 更新时会被覆盖。每次 VS Code 更新后，你需要重新应用此修改。

💻 使用示例

日历管理

"列出我所有的日历"
"我下周的日程安排是什么？"
"创建一个明天下午 2 点的会议，标题为 '团队同步'"
"添加一个周五上午 10 点的牙医预约，地点为 '主街 123 号'"
"删除名为 '已取消会议' 的会议"

提醒事项管理

"列出我未完成的提醒事项"
"显示我购物清单中的所有提醒事项"
"添加一个提醒：购买牛奶"
"创建一个明天下午 5 点给妈妈打电话的提醒"
"将 '购买牛奶' 标记为已完成"
"删除关于杂货的提醒"

高级功能（v0.3.0+）

"搜索包含 '会议' 的事件"
"搜索同时包含 '项目' 和 '评审' 的事件"
"我今天有什么安排？"
"显示我本周的日程安排"
"如果我安排一个下午 2 点到 3 点的会议，是否有冲突？"
"为接下来的 3 周创建 3 个每周团队会议"
"将牙医预约复制到我的工作日历"
"将 '旧日历' 中的所有事件移动到 '新日历'"
"删除所有已取消的事件"
"查找 'IDOL' 和 'Idol' 日历之间的重复事件"

开发者体验改进（v1.0.0）

"显示我接下来的 5 个即将到来的事件"
→ list_events(start_date: "2026-02-06", end_date: "2026-12-31", filter: "future", sort: "asc", limit: 5)

"显示我逾期的提醒事项"
→ list_reminders(filter: "overdue")

"预览在 2025 年之前从 '旧日历' 中删除哪些事件"
→ delete_events_batch(calendar_name: "Old Calendar", before_date: "2025-01-01", dry_run: true)

"创建一个下午 2 点的事件"（无需完整的 ISO8601 格式！）
→ create_event(start_time: "14:00", end_time: "15:00", ...)

📚 详细文档

支持的日历源

该工具可与任何同步到 macOS 日历应用的日历配合使用：

iCloud 日历
Google 日历
Microsoft Outlook/Exchange
CalDAV 日历
本地日历

同名日历区分（v0.6.0+）

如果你有来自不同源的同名日历（例如，iCloud 和 Google 中都有“工作”日历），可以使用 calendar_source 参数：

"在我的 iCloud 工作日历中创建一个事件"
→ create_event(calendar_name: "Work", calendar_source: "iCloud", ...)

"显示我的 Google 工作日历中的事件"
→ list_events(calendar_name: "Work", calendar_source: "Google", ...)

如果检测到歧义，错误消息将列出所有可用的源。

故障排除

| 问题 | 解决方案 | |---------|----------| | 服务器断开连接 | 使用 swift build -c release 重新构建 | | 权限被拒绝 | 在系统设置 > 隐私与安全中授予日历/提醒事项访问权限 | | 权限对话框未出现 | 请参阅授予权限中的 macOS Sequoia 解决方法 | | 未找到日历 | 确保日历在 macOS 日历应用中可见 | | 提醒事项不同步 | 检查系统设置中的 iCloud 同步设置 |

🔧 技术细节

当前版本：v1.3.1
框架：MCP Swift SDK v0.11.0
日历 API：EventKit（原生 macOS 框架）
传输方式：stdio
平台：macOS 13.0+（Ventura 及更高版本）
工具：提供 25 个工具，用于日历、事件、提醒事项、标签和高级操作

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE。

贡献说明

欢迎贡献代码！请随时提交拉取请求。

作者

由 Che Cheng (@kiki830621) 创建。

如果你觉得这个项目有用，请给它点个星！

che-ical-mcp

README

🚀 che-ical-mcp

🚀 快速开始

针对 Claude Desktop

选项 A：MCPB 一键安装（推荐）

选项 B：手动配置

针对 Claude Code (CLI)

从源代码构建（可选）

✨ 主要特性

📦 安装指南

安装要求

针对 Claude Desktop

方法 1：MCPB 一键安装（推荐）

方法 2：手动配置

针对 Claude Code (CLI)

从源代码构建（可选）

授予权限

💻 使用示例

日历管理

提醒事项管理

高级功能（v0.3.0+）

开发者体验改进（v1.0.0）

📚 详细文档

支持的日历源

同名日历区分（v0.6.0+）

故障排除

🔧 技术细节

📄 许可证

贡献说明

作者

Runtime guide

Hosted runtime

Local runtime / other methods