Google Calendar MCP Server

🚀 Google Calendar MCP Server

Google Calendar MCP Server 是一個基於模型上下文協議（MCP）的服務器，它具備全面的 Google Calendar 集成能力。該服務器允許 AI 助手和應用程序通過標準化協議與 Google Calendar 進行交互。

🚀 快速開始

運行服務器

# 啟動編譯後的服務器
npm start

# 或者在開發模式下運行
npm run dev

與 MCP 客戶端集成

將此服務器添加到您的 MCP 客戶端配置中：

{
  "servers": {
    "google-calendar": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

對於使用 MCP 擴展的 VS Code，將以下內容添加到 .vscode/mcp.json 中：

{
  "servers": {
    "google-calendar-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

認證設置

1. 創建服務賬戶：
   • 訪問 Google Cloud Console。
   • 導航到“IAM & Admin”>“服務賬戶”。
   • 創建一個新的服務賬戶。
   • 下載 JSON 密鑰文件。
2. 共享日曆訪問權限：
   • 打開 Google Calendar。
   • 進入日曆設置。
   • 與服務賬戶的電子郵件共享您的日曆。
   • 授予“對活動進行更改”的權限。
3. 配置環境：
   • 將 JSON 密鑰文件放在您的項目目錄中。
   • 使用正確的路徑更新 .env 文件。

✨ 主要特性

• 列出活動：從 Google Calendar 檢索活動，並支持過濾選項。
• 創建活動：可完全自定義地創建新的日曆活動。
• 更新活動：修改現有的日曆活動。
• 刪除活動：從日曆中移除活動。
• 列出日曆：獲取經過身份驗證的用戶可用的日曆。
• OAuth 認證：安全地訪問 Google Calendar API。

📦 安裝指南

前提條件

1. Google Cloud 項目：在 Google Cloud Console 中創建一個項目。
2. 啟用 Google Calendar API：為您的項目啟用日曆 API。
3. 服務賬戶：創建一個服務賬戶並下載 JSON 密鑰文件。

安裝步驟

1. 克隆此倉庫。
2. 安裝依賴項：

   npm install
   

3. 複製環境文件並進行配置：

   copy .env.example .env
   

4. 編輯 .env 文件，設置您的 Google 服務賬戶密鑰文件路徑：

   GOOGLE_SERVICE_ACCOUNT_KEY_FILE=./path/to/your/service-account-key.json
   

構建項目

# 構建 TypeScript 代碼
npm run build

# 開發模式，支持熱重載
npm run dev

# 類型檢查
npm run type-check

# 清理構建產物
npm run clean

💻 使用示例

list_events

使用各種過濾選項從 Google Calendar 檢索活動。

參數：

• calendarId（可選）：日曆 ID（默認值："primary"）
• timeMin（可選）：活動開始時間的下限（RFC3339 時間戳）
• timeMax（可選）：活動開始時間的上限（RFC3339 時間戳）
• maxResults（可選）：活動的最大數量（默認值：250）
• singleEvents（可選）：展開重複活動（默認值：true）
• orderBy（可選）：按“startTime”或“updated”對活動進行排序

create_event

在 Google Calendar 中創建一個新的活動。

參數：

• calendarId（可選）：日曆 ID（默認值："primary"）
• summary（必需）：活動標題
• description（可選）：活動描述
• start（必需）：包含 dateTime 和可選 timeZone 的開始日期/時間對象
• end（必需）：包含 dateTime 和可選 timeZone 的結束日期/時間對象
• location（可選）：活動地點
• attendees（可選）：包含電子郵件和顯示名稱的參與者對象數組
• recurrence（可選）：用於重複活動的 RRULE 字符串數組

update_event

更新現有的日曆活動。

參數：

• calendarId（可選）：日曆 ID（默認值："primary"）
• eventId（必需）：要更新的活動 ID
• summary（可選）：新的活動標題
• description（可選）：新的活動描述
• start（可選）：新的開始日期/時間
• end（可選）：新的結束日期/時間
• location（可選）：新的活動地點
• attendees（可選）：新的參與者列表

delete_event

從 Google Calendar 中刪除一個活動。

參數：

• calendarId（可選）：日曆 ID（默認值："primary"）
• eventId（必需）：要刪除的活動 ID

list_calendars

列出經過身份驗證的用戶可用的 Google 日曆。

參數：

• minAccessRole（可選）：最小訪問角色過濾器
• showDeleted（可選）：包括已刪除的日曆（默認值：false）
• showHidden（可選）：包括隱藏的日曆（默認值：false）

📚 詳細文檔

項目結構

src/
├── index.ts          # 主要的 MCP 服務器實現
├── types/            # TypeScript 類型定義
└── utils/            # 實用函數

.env.example          # 環境變量模板
tsconfig.json         # TypeScript 配置
package.json          # Node.js 依賴項和腳本

添加新工具

1. 定義一個 Zod 模式用於輸入驗證。
2. 創建一個 ToolSchema 定義。
3. 實現異步處理函數。
4. 在服務器中註冊該工具。
5. 添加全面的錯誤處理。

錯誤處理

所有工具都返回結構化響應：

// 成功響應
{
  content: [{ type: "text", text: JSON.stringify(result) }]
}

// 錯誤響應
{
  content: [{ type: "text", text: JSON.stringify(error) }],
  isError: true
}

🔧 技術細節

安全注意事項

• 切勿將服務賬戶密鑰提交到版本控制中。
• 對所有敏感配置使用環境變量。
• 實施適當的錯誤處理，避免信息洩露。
• 定期輪換服務賬戶密鑰。
• 遵循 Google Cloud 的安全最佳實踐。

貢獻指南

1. 分叉此倉庫。
2. 創建一個功能分支。
3. 進行更改並進行適當的測試。
4. 提交拉取請求。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

支持

如有問題和疑問：

• 查看 Google Calendar API 文檔。
• 查看 MCP 規範。
• 在本倉庫中創建一個問題。