Google Calendar MCP Server

Google Calendar MCP 服务

此 MCP 服务可访问您的 Google Calendar 日程，并允许您通过 MCP 接口管理日程。您可以将其与 Claude Desktop 或任何其他兼容 MCP 的客户端搭配使用。

要求

• Python 3.10 或更高版本 - MCP 要求使用 Python 3.10+
• 已启用 Calendar API 的 Google Cloud 项目
• 用于身份验证的 OAuth 凭据

功能

• 查看日程，可指定任意日期或日期范围
• 创建新日程，包含标题、时间、描述、地点和参与者
• 更新现有日程，填写新详情
• 常见日历操作的预置提示词

安装

1. 克隆此代码库：

   git clone <repository-url>
   cd google-calendar-mcp
   

2. 使用 Python 3.10 或更高版本创建虚拟环境：

   # Check your Python version
   python --version
   
   # Create a virtual environment with the correct Python version
   # For Python 3.10
   python3.10 -m venv venv
   # OR for Python 3.11
   python3.11 -m venv venv
   # OR for Python 3.12
   python3.12 -m venv venv
   
   # Activate the virtual environment
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. 使用 pip 安装依赖项：

   pip install -r requirements.txt
   

   也可以使用 uv 加快安装速度（推荐）：

   # Install uv if you don't have it
   curl -fsSL https://astral.sh/uv/install.sh | sh
   # On Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   
   # Install dependencies with uv
   uv pip install -r requirements.txt
   

4. 设置 Google Calendar API 凭据：

   a. 前往 Google Cloud Console b. 创建新项目或选择现有项目 c. 启用 Google Calendar API d. 创建 OAuth 凭据（桌面客户端 OAuth ID） e. 下载凭据 JSON 文件，并将其保存为项目目录中的 credentials.json

用法

与 Claude Desktop 搭配使用

1. 从官方网站安装 Claude Desktop

2. 在 Claude Desktop 中安装 MCP 服务：

   # Make sure you're in the project directory with the virtual environment activated
   mcp install calendar_mcp_server.py
   

3. 编辑 Claude Desktop 配置文件，将 Claude Desktop 配置为使用此 MCP 服务：

   • 在 /path/to/your/claude_desktop_config.json（Mac）或操作系统对应的位置找到 Claude 配置文件
   • 添加或修改配置，以包含 Google Calendar MCP：

   {
     "Google Calendar": {
       "command": "/path/to/your/venv/bin/mcp",
       "args": [
         "run",
         "/path/to/your/project/calendar_mcp_server.py"
       ]
     }
   }
   

   • 将 /path/to/your/venv/ 替换为虚拟环境的实际路径
   • 将 /path/to/your/project/ 替换为项目目录的实际路径

4. 验证 MCP 服务是否正常运行：

   • 打开 Claude Desktop
   • 点击左下角的设置图标（齿轮）
   • 在设置菜单中选择“Developer”
   • 在“Active MCP Servers”下，您应能看到“Google Calendar”
   • 如果 MCP 服务运行正常，您会看到绿色状态指示灯
   • 如果列表中没有该服务或显示错误，请确保服务正在运行

5. 现在可以使用如下提示词：

   Show me my events for today
   Create a meeting with John tomorrow at 2pm
   

与 Cursor 搭配使用

1. 配置 Cursor：

   • 打开 Cursor。
   • 前往 Settings（通常是齿轮图标，也可以通过命令面板打开）。
   • 前往 Cursor Settings > MCP。
   • 点击 Add New Global MCP Server。
     • 添加或修改配置，以包含 Google Calendar MCP：

     {
     "Google Calendar": {
        "command": "/path/to/your/venv/bin/mcp",
        "args": [
           "run",
           "/path/to/your/project/calendar_mcp_server.py"
        ]
     }
     }
     

     • 将 /path/to/your/venv/ 替换为虚拟环境的实际路径
     • 将 /path/to/your/project/ 替换为项目目录的实际路径

2. 在 Cursor 中使用：

   • 在 Cursor 中与 AI 聊天时（例如使用“Agent”模式或其他可调用 MCP 的功能），它现在应该能够连接到正在运行的 Google Calendar MCP 服务。
   • 您可以使用与日历相关的提示词，例如：

     显示我今天的日程
     明天下午 2 点和 John 安排一场会议
     

   • 如果配置正确且服务正在运行，Cursor 应会将这些请求路由到您的本地服务。

使用 MCP Inspector 在开发模式下运行：

如果您正在开发或调试 MCP 服务，请使用：

mcp dev calendar_mcp_server.py

这将提供额外的调试信息，以及一个用于检查请求和响应的 Web 界面。

资源

该服务提供以下 MCP 资源：

• calendar://events/{date} - 返回指定日期的活动

示例用法：

calendar://events/today
calendar://events/tomorrow
calendar://events/2023-07-15

工具

该服务提供以下工具：

1. list_events(date_start, date_end=None) - 列出指定日期范围内的活动
2. create_event(summary, start_datetime, end_datetime, ...) - 创建新的日历活动
3. update_event(event_id, ...) - 更新现有活动

提示词

用于简化常见操作的预置提示词：

1. today_events - 快速查看今天的日历
2. schedule_meeting - 引导创建新的会议

身份验证

首次使用时，服务会打开浏览器窗口进行 Google OAuth 身份验证。授权应用后，您的凭据将保存到 token.json，供日后使用。

故障排除

• Python 版本问题：此项目需要 Python 3.10 或更高版本。如果您看到类似 No matching distribution found for mcp[cli] 的错误，请检查 Python 版本。
• 身份验证错误：请确保 credentials.json 文件放置正确且具有适当的权限。
• MCP 安装问题：尝试使用 uv 而非 pip，以获得更可靠的安装体验。

注意事项

• 服务使用 UTC 时间戳。活动时间会以本地时区显示。
• 使用此服务需要从 Google Cloud Console 获取有效的 credentials.json 文件。
• 首次登录后，您的身份验证令牌将保存到 token.json。