MCP Gcalendar

MCP日历服务器

A. 模型上下文协议（MCP） 服务器为AI助手提供谷歌日历集成。遵循干净的建筑原则和全面的类型安全。

特性

• 活动管理：创建、更新、删除和检索日历事件
• 可用性检查：查找空闲时隙并检测日程安排冲突
• 事件搜索：按标题和描述中的文本搜索事件
• 重复发生的事件：使用灵活的模式创建和管理重复事件
• 安全认证：按请求OAuth2令牌（无服务器端凭据存储）

技术与模式

核心技术：

• FastMCP -基于装饰器的现代MCP服务器框架
• Pydantic v2 -数据验证和设置管理
• 谷歌日历API -通过官方Python客户端集成日历

设计模式：

• 存储库模式 -数据访问抽象层
• 服务层模式 -业务逻辑分离
• 依赖注入 -通过基于协议的接口实现松耦合
• 中间件模式 -请求/响应处理管道
• 类型安全模式 -适用于所有I/O操作的Pydantic模型

快速开始

先决条件

• Python 3.13+
• 紫外线 包管理器
• 启用日历API的谷歌云项目
• OAuth2凭据来自 谷歌云控制台

安装

# Clone and install
git clone 
cd mcp_calendar
uv sync

# Configure OAuth credentials
cp .env.example .env
# Edit .env with your OAuth client ID and secret

跑步

# Start server
uv run python -m src.main

# With debug logging
MCP_CALENDAR_DEBUG=true uv run python -m src.main

认证

服务器使用 按请求OAuth2身份验证:

• 客户端在每次工具调用时提供访问令牌
• 无服务器端凭据存储或令牌刷新
• 出于安全考虑，令牌被排除在LLM上下文之外

通过环境变量配置服务器OAuth客户端凭据：

MCP_CALENDAR_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
MCP_CALENDAR_OAUTH_CLIENT_SECRET=your-client-secret

可用工具

• create_event -创建新的日历事件
• create_event_allday -创建全天活动
• update_event -修改现有事件
• delete_event -删除事件
• get_event_details -检索事件信息
• check_availability -查找空闲时段
• search_events -按文本搜索事件
• get_events_range -获取日期范围内的事件
• create_recurring_event -创建重复事件
• update_recurrence -修改重复模式
• list_calendars -列出可用日历

MCP客户端集成

克劳德桌面

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "calendar": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.main"],
      "cwd": "/path/to/mcp_calendar",
      "env": {
        "MCP_CALENDAR_OAUTH_CLIENT_ID": "your-client-id",
        "MCP_CALENDAR_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

其他MCP客户端

服务器按照MCP协议通过stdio进行通信。作为子进程运行，并通过stdin/stdout进行通信。

项目结构

src/
├── main.py                 # Entry point
├── core/                   # Core business logic & MCP server
├── services/              # Service layer (auth, calendar)
├── repositories/          # Data access layer
├── models/               # Pydantic data models
├── interfaces/           # Protocol-based abstractions
└── config/              # Configuration & logging

许可证

MIT许可证-有关详细信息，请参阅许可证文件。