kristofferv98
服务介绍
MCP iCal 服务器
🗓️ macOS 日历管理的代理驱动方案
该项目基于 Omar-V2/mcp-ical，并使用基于代理的方法重新实现了用户交互层。
🌟 概览
通过专用的人工智能代理，改变您与 macOS 日历的互动方式！此 MCP iCal 服务器利用 OpenAI Agent SDK 提供了一个强大且统一的日历操作入口点。
与传统的 MCP 实现不同，该服务器采用基于代理的方法：
- 🧠 单一工具接口：只有一个 MCP 工具 (
send_to_calendar_agent)，它将任务委托给一个专门的日历代理 - 🤖 有状态对话：代理在同一个会话中的请求之间保持上下文
- 🔄 零配置操作：自然语言处理由专门的代理自动处理
你：“下周我的日程是什么？”
Claude：“让我查一下……”
[日历代理处理请求并返回清晰的日程]
你：“明天中午和 Sarah 安排一个午餐会议”
Claude：“事件已创建：与 Sarah 的午餐，明天中午 12:00”
✨ 功能
📅 事件创建
立即将自然语言转换为日历事件！
“安排下星期四下午 1 点在 Bistro Garden 的团队午餐”
↓
📎 创建：团队午餐
📅 星期四，下午 1:00
📍 Bistro Garden
支持的功能：
- 自定义日历选择
- 地点和备注
- 智能提醒
- 循环事件
高级用户示例：
🔄 循环事件：
“每周一上午 9 点设置我的团队同步，并提前 15 分钟提醒”
📝 详细事件：
“在工程日历中安排明天下午 2 到 4 点的产品评审会议，
添加关于审查 Q1 指标的备注，并提前 1 小时提醒我”
📱 多日历支持：
“在我的个人日历中添加下周三下午 3 点的牙医预约”
🔍 智能日程管理和可用性
通过自然查询快速访问您的日程：
“下周我的日程是什么？”
↓
📊 以智能格式显示您的即将到来的事件
“下周二我什么时候可以安排一个两小时的会议？”
↓
🕒 找到的可用时间：
• 周二上午 10:00 - 中午 12:00
• 周二下午 2:00 - 下午 4:00
✏️ 智能事件更新
自然地修改事件：
“将明天的团队会议改到下午 3 点”
↓
✨ 会议重新安排到下午 3:00
更新功能：
- 时间和日期修改
- 日历转移
- 地点更新
- 添加备注
- 提醒调整
- 循环模式更改
📊 日历管理
- 查看所有可用日历
- 智能日历建议
- 无缝集成 Google 日历（当与 iCloud 配置时）
💡 专业提示：由于您可以在自定义日历中创建事件，如果您将 Google 日历与 iCloud 日历同步，您可以使用此 MCP 服务器在 Google 日历中创建事件！只需在创建或更新事件时指定 Google 日历即可。
🚀 快速开始
💡 注意：虽然这些说明侧重于使用 Claude for Desktop 设置 MCP 服务器，但此服务器可以与任何兼容 MCP 的客户端一起使用。有关使用不同客户端的更多详细信息，请参阅 MCP 文档。
前提条件
- uv 包管理器
- 配置了 Calendar 应用程序的 macOS
- 一个 MCP 客户端 - 推荐使用 Claude for desktop- OpenAI API 密钥（设置为
OPENAI_API_KEY环境变量）
安装
虽然此 MCP 服务器可以与任何兼容 MCP 的客户端一起使用，但以下说明是针对桌面版 Claude 的。
- 克隆和设置
bash
克隆仓库
git clone https://github.com/yourusername/mcp-ical.git
cd mcp-ical
安装依赖
uv sync
- 使用 API 密钥配置桌面版 Claude
创建或编辑 ~/Library/Application Support/Claude/claude_desktop_config.json 并将您的 OpenAI API 密钥作为环境变量包含在内：
json
{
"mcpServers": {
"mcp-ical": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-ical",
"run",
"mcp-ical"
],
"env": {
"OPENAI_API_KEY": "your-api-key-here"
}
}
}
}
- 启动 Claude 以访问日历
⚠️ 重要：Claude 必须从终端启动才能正确请求日历权限。直接从 Finder 启动不会触发权限提示。
bash
/Applications/Claude.app/Contents/MacOS/Claude
- 开始使用！
尝试：“下周我的日程安排是什么？”
🔑 注意：当您首次使用与日历相关的命令时，macOS 将提示授予日历访问权限。只有按照上述方式从终端启动 Claude 时才会出现此提示。
🧪 测试
⚠️ 警告：测试将创建临时日历和事件。虽然清理是自动的，但仅应在开发环境中运行测试。
bash
安装开发依赖
uv sync --dev
运行测试套件
uv run pytest tests
🧠 工作原理
此实现使用了一种独特的架构：
- 向客户端暴露一个单一的 MCP 工具 (
send_to_calendar_agent) - 当调用时，该工具将请求传递给使用 OpenAI Agent SDK 构建的专业日历代理
- 代理处理自然语言请求并调用适当的日历操作
- 结果被格式化并返回给客户端
这种方法提供了几个优点：
- 简化客户端集成：只需调用一个工具
- 改进上下文处理：代理维护会话状态
- 更自然的交互：专业代理理解特定于日历的术语和意图
❓ 此项目与原始项目的不同之处
此实现保留了 Omar-V2/mcp-ical 中大部分核心日历功能，但完全重新实现了用户交互层：
- 单一入口点：我们实现了一个单一入口点，该入口点将请求委托给由 OpenAI 支持的代理，而不是直接向客户端暴露多个 MCP 工具
- 基于代理的处理：添加了 OpenAI 代理来处理自然语言理解和转换为日历操作
- 有状态的对话：在同一会话中的请求之间添加了对话上下文跟踪
- 简化的客户端集成：客户端只需要知道一个工具，而不需要了解多个日历操作
核心日历操作（事件创建、列表等）和 macOS 集成基本保持不变。
🐛 已知问题
重复事件
- 非标准的重复计划可能无法始终正确设置
- 更强大的 LLM 模型可以获得更好的结果
- 重复全天事件的提醒时间可能会有一天的偏差
🤝 贡献
欢迎反馈和贡献！以下是您可以帮助的方式：
- 叉取仓库
- 创建您的功能分支
- 提交您的更改
- 推送到分支
- 打开拉取请求
📝 许可证
此项目根据 MIT 许可证发布 - 请参阅 LICENSE 文件获取详细信息。
📝 致谢- 原始项目: 基于 Omar-V2/mcp-ical 由 Omar-V2 创建
- 使用 Model Context Protocol 构建
- 日历集成使用 PyObjC 构建
- 代理功能由 OpenAI Agent SDK 提供支持
