使用说明

MCP iCal服务器

🗓️ 基于代理的macOS日历管理

该项目基于 Omar-V2/mcp 使用基于代理的方法重新实现用户交互层。

🌟 概述

使用专用的AI代理改变您与macOS日历的交互方式！此MCP iCal服务器利用OpenAI Agent SDK为您的所有日历操作提供了一个强大的入口点。

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

🧠 单工具界面：只需一个MCP工具(send_to_calendar_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日历

💡 专业提示：由于您可以在自定义日历中创建事件，如果您的Google日历与iCloud日历同步，您也可以使用此MCP服务器在Google日历中创建活动！只需在创建/更新事件时指定谷歌日历。

🚀 快速开始

💡 备注：虽然这些说明侧重于使用Claude for Desktop设置MCP服务器，但此服务器可以与任何兼容MCP的客户端一起使用。有关使用不同客户端的更多详细信息，请参阅 MCP文件.

先决条件

uv包管理器
已配置日历应用程序的macOS
MCP客户端- Claude桌面版推荐
OpenAI API密钥（设置为 OPENAI_API_KEY 环境变量）

安装

虽然此MCP服务器可以与任何兼容MCP的客户端一起使用，但以下说明适用于桌面版的Claude。

克隆和设置

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

# Install dependencies
uv sync

使用API密钥为桌面配置Claude

创建或编辑 ~/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"
            }
        }
    }
}

启动Claude以访问日历

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

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

开始使用！

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

🧠 运作原理

此实现使用了一种独特的架构：

一个MCP工具(send_to_calendar_agent)向客户公开
调用时，此工具将请求传递给使用OpenAI agent SDK构建的专用日历代理
代理处理自然语言请求并调用相应的日历操作
结果被格式化并返回给客户端

这种方法有几个优点：

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

❓ 这个项目与原始项目有何不同

此实现维护了来自以下方面的大部分核心日历功能 Omar-V2/mcp 但完全重新实现了用户交互层：

单一入口点：我们没有将多个MCP工具直接暴露给客户端，而是实现了一个委托给OpenAI驱动的代理的单一入口点
基于代理的处理：添加了一个OpenAI代理来处理自然语言理解和日历操作的翻译
有状态的对话：添加了同一会话中请求之间的对话上下文跟踪
简化客户端集成：客户只需要知道一个工具，而不是多个日历操作

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

🐛 已知问题

重复发生的事件

非标准定期计划可能并不总是设置正确
使用更强大的LLM模型获得更好的结果
全天重复事件的提醒时间可能会关闭一天

🤝 贡献

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

分叉存储库
创建功能分支
提交您的更改
推到分支
打开拉取请求

📝 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

📝 致谢

原始项目：基于 Omar-V2/mcp 靠近 Omar-V2
内置于模型上下文协议
日历集成与 PyObjC
代理功能由 OpenAI代理SDK