MCP iCal Server

MCP iCal 服务

🌟 概述

用自然语言改变你与 macOS 日历的交互方式！mcp-ical 服务利用模型上下文协议（MCP），将日历管理变成对话式体验。

You: "What's my schedule for next week?"
Claude: "Let me check that for you..."
[Displays a clean overview of your upcoming week]

You: "Add a lunch meeting with Sarah tomorrow at noon"
Claude: "✨ 📅 Created: Lunch with Sarah Tomorrow, 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

✏️ 智能更新事件

以自然的方式修改事件：

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

更新功能

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

📊 日历管理

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

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

🚀 快速开始

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

前提条件

• uv 包管理器
• 已配置日历应用的 macOS
• MCP 客户端——推荐使用 Claude for Desktop

安装

虽然此 MCP 服务可与任何兼容 MCP 的客户端搭配使用，但以下说明针对 Claude for Desktop。

1. 克隆并设置

   # 克隆仓库
   git clone https://github.com/Omar-V2/mcp-ical.git
   cd mcp-ical
   
   # 安装依赖项
   uv sync
   

2. 配置 Claude for Desktop

   创建或编辑 ~/Library/Application\ Support/Claude/claude_desktop_config.json：

   {
       "mcpServers": {
           "mcp-ical": {
               "command": "uv",
               "args": [
                   "--directory",
                   "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-ical",
                   "run",
                   "mcp-ical"
               ]
           }
       }
   }
   

3. 启动 Claude 以访问日历

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

   在终端中运行以下命令。

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

   ⚠️ 警告：或者，你也可以手动授予日历访问权限，但这需要修改系统文件，只有在你了解相关风险时才应这样做。

4. 开始使用！

   试试：“我下周的日程安排怎么样？”
   

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

🧪 测试

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

# Install dev dependencies
uv sync --dev

# Run test suite
uv run pytest tests

🐛 已知问题

重复事件

• 非标准的重复安排可能无法始终正确设置
• 与 Haiku 相比，Claude 3.5 Sonnet 的效果更好
• 重复的全天事件的提醒时间可能会偏差一天

🤝 贡献

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

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

📝 许可证

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

🙏 致谢

• 基于 Model Context Protocol 构建
• macOS 日历集成基于 PyObjC 构建