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。