Google Calendar MCP Server

🚀 Google Calendar MCP 服务器

Google Calendar MCP 服务器可将 Google 日历工具开放给任何兼容 MCP 的客户端（例如 Claude Desktop、Cursor MCP CLI）。它具备以下功能：

• 列出指定时间窗口内的日程事件
• 创建日程事件
• 根据日程摘要删除日程事件

🚀 快速开始

🔍 前提条件

• Python 3.11 及以上版本
• 拥有一个启用了 Google 日历 API 的 Google Cloud 项目，并具备 OAuth 2.0 客户端 ID（桌面应用类型）
• 已将 credentials.json 文件下载到本地（请勿将其提交到版本控制系统）

⚙️ 安装指南

1. 克隆项目并安装依赖

uv sync  # 或者：pip install -e .

2. 启用 Google 日历 API 并下载 OAuth 凭证
   • 访问 Google Cloud 控制台 → API 和服务 → 凭证。
   • 创建 OAuth 客户端 ID，应用类型选择“桌面应用”。
   • 下载 JSON 文件，并将其保存为项目根目录下的 credentials.json。
3. 首次运行 / OAuth 授权 首次调用任何工具时，会打开浏览器进行授权，并在本地生成 token.json 文件（该文件会被 git 忽略）。

🚀 启动 MCP 服务器

python -m src.service  # 非服务器入口
python main.py         # 通过标准输入输出启动 MCP

在兼容 MCP 的客户端中，可将 main.py 作为命令来使用该服务。

💻 使用示例

基础用法

以下是如何在 MCP 客户端配置文件中使用该服务器的示例：

{
  "mcpServers": {
    "google-calendar": {
      "command": "python",
      "args": ["main.py"],
      "env": {}
    }
  }
}

高级用法

获取日程事件

# 调用 get_google_calendar_events 函数获取日程事件
get_google_calendar_events(maxResults, calendarId="primary", singleEvents=True, orderBy="startTime", timeMin=None, timeMax=None)
# 返回值示例：[{ "title": "会议", "start-time": "2025-08-08T09:00:00+06:00", "end-time": "2025-08-08T10:00:00+06:00" }]

创建日程事件

# 调用 create_google_calendar_event 函数创建日程事件
from datetime import datetime
create_google_calendar_event(summary="新会议", start=datetime(2025, 8, 8, 9, 0), end=datetime(2025, 8, 8, 10, 0), description="重要会议", location="会议室 1", time_zone="Asia/Dhaka")
# 返回创建的日程事件的 HTML 链接（如果可用）

删除日程事件

# 调用 delete_google_calendar_event 函数删除日程事件
delete_google_calendar_event(event_name="新会议")
# 删除第一个摘要完全匹配的日程事件

📚 详细文档

工具列表

• get_google_calendar_events(maxResults, calendarId="primary", singleEvents=True, orderBy="startTime", timeMin=None, timeMax=None)
  • 功能：列出指定时间窗口内的日程事件。
  • 返回值：返回一个列表，列表中的每个元素是一个字典，包含日程的标题、开始时间和结束时间。
• create_google_calendar_event(summary, start: datetime, end: datetime, description=None, location=None, time_zone="Asia/Dhaka")
  • 功能：创建一个新的日程事件。
  • 返回值：返回创建的日程事件的 HTML 链接（如果可用）。
• delete_google_calendar_event(event_name: str)
  • 功能：删除第一个摘要完全匹配的日程事件。

MCP 客户端配置示例

以下是一个 MCP 客户端配置文件的 JSON 片段示例：

{
  "mcpServers": {
    "google-calendar": {
      "command": "python",
      "args": ["main.py"],
      "env": {}
    }
  }
}

⚠️ 注意事项

• 请确保 credentials.json 和 token.json 文件不被提交到版本控制系统。
• 时间字符串必须符合 RFC3339 格式并包含时区信息（例如，2025-08-08T00:00:00+06:00）。
• 全天日程事件返回的是 date 字符串，而不是 dateTime。