MCP iCal Server

MCP iCal Server

本项目基于 Omar-V2/mcp-ical，并采用基于 Agent 的方法重新实现了用户交互层。

🌟 概述

使用专用 AI Agent，改变你与 macOS 日历的交互方式！此 MCP iCal 服务借助 OpenAI Agent SDK，为所有日历操作提供一个强大的统一入口。

与公开多个工具的传统 MCP 实现不同，此服务采用基于 Agent 的方法：

• 🧠 单一工具接口：仅需一个 MCP 工具（send_to_calendar_agent），即可将请求交由专用日历 Agent 处理
• 🤖 有状态对话：Agent 会在同一会话的请求之间保留上下文
• 🔄 零配置运行：专用 Agent 会自动处理自然语言

You: "What's my schedule for next week?"
Claude: "Let me check that for you..."
[Calendar agent processes request and returns clean schedule]

You: "Add a lunch meeting with Sarah tomorrow at noon"
Claude: "Event created: Lunch with Sarah, tomorrow at 12:00 PM"

✨ 功能

📅 创建事件

即时将自然语言转换为日历事件！

"Schedule a team lunch next Thursday at 1 PM at Bistro Garden"
↓
📎 Created: Team Lunch
   📅 Thursday, 1:00 PM
   📍 Bistro Garden

支持的功能：

• 选择自定义日历
• 设置地点和备注
• 智能提醒
• 循环事件

高级用户示例：

🔄 Recurring Events:
"Set up my weekly team sync every Monday at 9 AM with a 15-minute reminder"

📝 Detailed Events:
"Schedule a product review meeting tomorrow from 2-4 PM in the Engineering calendar, 
add notes about reviewing Q1 metrics, and remind me 1 hour before"

📱 Multi-Calendar Support:
"Add a dentist appointment to my Personal calendar for next Wednesday at 3 PM"

🔍 智能日程管理与可用时间查询

通过自然语言查询，快速查看日程：

"What's on my calendar for next week?"
↓
📊 Shows your upcoming events with smart formatting

"When am I free to schedule a 2-hour meeting next Tuesday?"
↓
🕒 Available time slots found:
   • Tuesday 10:00 AM - 12:00 PM
   • Tuesday 2:00 PM - 4:00 PM

✏️ 智能更新事件

轻松修改事件：

"Move tomorrow's team meeting to 3 PM instead"
↓
✨ Meeting rescheduled to 3:00 PM

更新功能：

• 修改时间和日期
• 转移日历
• 更新地点
• 添加备注
• 调整提醒
• 更改循环模式

📊 日历管理

• 查看所有可用日历
• 智能推荐日历
• 配置 iCloud 后，无缝集成 Google Calendar

💡 专业提示：你可以在自定义日历中创建事件。如果 Google Calendar 已与 iCloud 日历同步，就可以使用此 MCP 服务在 Google Calendar 中创建事件！创建或更新事件时，只需指定 Google Calendar 即可。

🚀 快速开始

💡 注意：以下说明重点介绍如何将 MCP 服务与 Claude for Desktop 搭配使用，但此服务也可用于任何兼容 MCP 的客户端。有关使用其他客户端的详细信息，请参阅 MCP 文档。

前置条件

• uv 包管理器
• 已配置日历应用的 macOS
• MCP 客户端——推荐使用 Claude for desktop
• OpenAI API 密钥（设置为 OPENAI_API_KEY 环境变量）

安装

此 MCP 服务可用于任何兼容 MCP 的客户端，但以下说明适用于 Claude for desktop。

1. 克隆并设置

# Clone the repository
git clone https://github.com/yourusername/mcp-ical.git
cd mcp-ical

# Install dependencies
uv sync

2. 使用 API 密钥配置 Claude for Desktop

创建或编辑 ~/Library/Application\ Support/Claude/claude_desktop_config.json，并将 OpenAI API 密钥作为环境变量添加：

{
    "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"
            }
        }
    }
}

3. 启动 Claude 以访问日历

⚠️ 重要提示：必须从终端启动 Claude，才能正确请求日历权限。直接从 Finder 启动不会触发权限提示。

/Applications/Claude.app/Contents/MacOS/Claude

4. 开始使用！

Try: "What's my schedule looking like for next week?"

🔑 注意：首次使用日历相关命令时，macOS 会提示授予日历访问权限。只有按照上述说明从终端启动 Claude 后，才会显示此提示。

🧪 测试

⚠️ 警告：测试会创建临时日历和事件。虽然会自动清理，但请仅在开发环境中运行测试。

# Install dev dependencies
uv sync --dev

# Run test suite
uv run pytest tests

🧠 工作原理

此实现采用了独特的架构：

1. 向客户端公开一个 MCP 工具（send_to_calendar_agent）
2. 调用该工具时，它会将请求传递给一个使用 OpenAI Agent SDK 构建的专用日历 Agent
3. 该 Agent 处理自然语言请求，并调用相应的日历操作
4. 格式化结果并返回给客户端

这种方法有以下几个优点：

• 简化客户端集成：只需调用一个工具
• 改进上下文处理：Agent 会维护对话状态
• 交互更自然：专用 Agent 能够理解特定于日历的术语和意图

❓ 此项目与原项目的区别

此实现保留了 Omar-V2/mcp-ical 的大部分核心日历功能，但完全重新实现了用户交互层：

1. 单一入口：我们没有直接向客户端公开多个 MCP 工具，而是实现了一个单一入口，由它委托给 OpenAI 驱动的 Agent
2. 基于 Agent 的处理：添加了一个 OpenAI Agent，用于理解自然语言并将其转换为日历操作
3. 有状态的对话：添加了请求之间的对话上下文跟踪，以便在同一会话中使用
4. 简化客户端集成：客户端只需了解一个工具，而不必了解多个日历操作

核心日历操作（创建事件、列出事件等）和 macOS 集成与原始实现基本保持不变。

🐛 已知问题

重复事件

• 非标准的重复日程可能无法始终正确设置
• 使用能力更强的大模型可获得更好的结果
• 全天重复事件的提醒时间可能会偏差一天

🤝 贡献

欢迎反馈和贡献！以下是你可以提供帮助的方式：

1. Fork 此仓库
2. 创建功能分支
3. 提交更改
4. 推送到该分支
5. 创建 Pull Request

📝 许可证

此项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

📝 致谢

• 原始项目：基于 Omar-V2 的 Omar-V2/mcp-ical
• 使用 Model Context Protocol 构建
• 日历集成使用 PyObjC 构建
• Agent 能力由 OpenAI Agent SDK 提供