Google Calendar

🚀 谷歌日曆 MCP 服務器

本項目是一個使用 TypeScript 構建的 Model Context Protocol (MCP) 服務器，集成了谷歌日曆功能，能為用戶提供便捷的日曆管理與操作體驗。

🚀 快速開始

本服務器使用 TypeScript 構建，集成了谷歌日曆功能，支持 OAuth 2.0 認證，可實現日曆及事件的管理操作，還能通過 Server-Sent Events (SSE) 進行即時更新推送，並且兼容 Claude 和其他 MCP 兼容的 AI 助手。

✨ 主要特性

• 無縫谷歌日曆集成：支持 OAuth 2.0 認證，確保與谷歌日曆的順暢連接。
• 持久化令牌存儲：實現自動認證，無需頻繁手動操作。
• 日曆管理：可列出並操作日曆及其事件，方便用戶管理日程。
• 事件全生命週期操作：支持創建、讀取、更新和刪除日曆事件，滿足多樣化的日程需求。
• 按日期範圍獲取事件：能查詢指定時間內的日曆事件，便於用戶快速定位所需信息。
• 即時更新推送：支持 Server-Sent Events (SSE) 傳輸協議，及時推送事件更新。
• 簡單集成：兼容 Claude 和其他 MCP 兼容的 AI 助手，方便與其他工具配合使用。

📦 安裝指南

安裝命令

npm install -g mcp-google-calendar

或直接運行：

npx -y mcp-google-calendar

先決條件

1. Node.js（v16 或更高版本）
2. 谷歌雲平臺賬戶
3. 谷歌日曆 API 已啟用
4. OAuth 2.0 憑證配置完成

配置指南

1. 谷歌雲平臺配置

1. 訪問 谷歌雲控制檯
2. 創建新項目或選擇現有項目
3. 啟用谷歌日曆 API：
   • 進入 "APIs & Services" > "Library"
   • 搜索 "Google Calendar API"
   • 點擊 "Enable"
4. 配置 OAuth 一致性界面：
   • 訪問 "APIs & Services" > "OAuth consent screen"
   • 選擇 "External" 用戶類型（或 "Internal" 對於谷歌 Workspace）
   • 填寫所需信息：
     • 應用名稱：mcp-calendar
     • 用戶支持郵箱：(你的郵箱)
     • 開發者聯繫方式：(你的郵箱)
   • 添加權限範圍：
     • 點擊 "Add or Remove Scopes"
     • 找到並選擇 "https://www.googleapis.com/auth/calendar.events"
     • 將你的郵箱添加為測試用戶
   • 完成設置流程
5. 創建 OAuth 憑證：
   • 進入 "Credentials" 部分
   • 點擊 "Create Credentials" > "OAuth Client ID"
   • 選擇應用類型為 "Desktop app"
   • 命名（例如：MCP Calendar Desktop Client）
   • 下載 JSON 文件並保存至項目目錄下的 credentials.json

2. 環境配置

在項目根目錄創建一個 .env 文件：

# 服務器配置
PORT=3420

# 谷歌日曆 API 配置
CREDENTIALS_PATH=./credentials.json

💻 使用示例

啟動服務器

基礎用法

使用標準 WebSocket 運行：

npx -y mcp-google-calendar

高級用法

使用 Server-Sent Events (SSE) 運行：

npx -y mcp-google-calendar --sse

集成 Claude Desktop

在 claude_desktop_config.json 中添加如下配置：

{
   "mcpServers": {
      "mcp-google-calendar": {
         "command": "npx",
         "args": ["-y", "mcp-google-calendar"]
      }
   }
}

功能模塊使用示例

認證授權

1. 獲取授權碼：通過 OAuth 2.0 獲取訪問令牌所需的授權碼
2. 令牌刷新：實現令牌的自動刷新機制，確保長期有效訪問

日曆管理

基礎用法

// 日曆創建
const calendar = await createCalendar({
  summary: 'My New Calendar',
  description: 'This is a new calendar created via API'
});

高級用法

• 日曆讀取：獲取指定日曆的詳細信息，包括名稱、描述等
• 日曆更新：修改已存在的日曆屬性，例如更新日曆名稱或描述
• 日曆刪除：移除不再需要的日曆

事件管理

基礎用法

// 事件創建
const event = await createEvent({
  calendarId: 'primary',
  summary: 'Meeting with Team',
  description: 'Discuss Q4 project plan',
  start: {
    timeZone: 'Asia/Shanghai',
    dateTime: '2023-10-05T09:00:00'
  },
  end: {
    timeZone: 'Asia/Shanghai',
    dateTime: '2023-10-05T10:30:00'
  }
});

高級用法

// 事件查詢
const events = await listEvents({
  calendarId: 'primary',
  timeMin: '2023-10-01T00:00:00',
  timeMax: '2023-10-31T23:59:59'
});

// 事件更新
const updatedEvent = await updateEvent({
  calendarId: 'primary',
  eventId: 'event_id_123',
  summary: 'Updated Meeting'
});

// 事件刪除
await deleteEvent({
  calendarId: 'primary',
  eventId: 'event_id_123'
});

即時推送

通過 SSE 實現事件的即時更新通知，訂閱特定日曆的所有事件變更。

📚 詳細文檔

項目結構

src/
├── index.ts          # 入口文件
├── calendar.ts       # 日曆管理模塊
├── event.ts          # 事件管理模塊
└── auth.ts           # 認證授權模塊

快速上手

1. 安裝依賴：

npm install @types/googleapis google-auth-library

2. 初始化項目：

npx tsinit

3. 編寫代碼並運行：

npm run dev

🔧 技術細節

本項目使用 TypeScript 構建，藉助谷歌日曆 API 實現日曆及事件的管理功能。通過 OAuth 2.0 進行認證授權，確保數據安全。採用 Server-Sent Events (SSE) 實現即時更新推送，提升用戶體驗。同時，項目結構清晰，各模塊分工明確，便於開發和維護。

📄 許可證

文檔未提及相關許可證信息。

⚠️ 重要提示

⚠️ 重要提示

1. 憑證管理：確保 credentials.json 文件的安全性，避免洩露敏感信息。
2. 權限控制：嚴格限制 API 調用的權限範圍，防止越權操作。
3. 日誌監控：即時監控 API 請求和響應，及時發現異常行為。
4. 錯誤處理：針對不同的 API 錯誤碼和異常情況，設計完善的容錯機制。