Google Calendar

🚀 谷歌日曆 MCP 項目指南

本項目旨在創建一個與 Google Calendar 集成的工具，藉助 Model Context Protocol (MCP) 以及自然語言處理能力，讓你能在 Claude 中輕鬆管理和查詢日曆事件。

🚀 快速開始

環境要求

• 操作系統：支持 Node.js 的任何操作系統（推薦 Linux 或 macOS）
• Node.js 版本：16.0+
• npm 版本：6.0+

項目初始化

mkdir google-calendar-mcp
cd google-calendar-mcp
npm init -y

安裝依賴

npm install @modelcontextprotocol/sdk googleapis google-auth-library zod
npm install -D @types/node typescript

創建 tsconfig.json 文件

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

更新 package.json

{
  "type": "module",
  "scripts": {
    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\""
  }
}

📦 安裝指南

認證配置

獲取 OAuth 憑據

1. 創建 OAuth 應用：

   • 登錄 Google Cloud Console
   • 創建新項目或選擇現有項目
   • 轉到 "APIs & Services" > "Credentials"
   • 點擊 "Create Credentials" 並選擇 "OAuth client ID"

2. 設置 OAuth 作用域：

   • 請求以下作用域：https://www.googleapis.com/auth/calendar.readonly, https://www.googleapis.com/auth/calendar

配置環境變量

創建一個 .env 文件（不要提交到版本控制系統）：

GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REDIRECT_URI=http://localhost
GOOGLE_REFRESH_TOKEN=your_refresh_token_here

項目結構

mkdir src

💻 使用示例

實現核心功能

導入依賴

在 src/index.ts 中導入必要的模塊：

import { GoogleCalendar } from '@modelcontextprotocol/google-calendar';

初始化日曆工具

創建一個 MCP 工具類：

export class GoogleCalendarMCP extends Tool {
  private calendar: Calendar;

  constructor() {
    super('google_calendar', 'Google Calendar Management');
    this.calendar = new Calendar({
      client_id: process.env.GOOGLE_CLIENT_ID,
      client_secret: process.env.GOOGLE_CLIENT_SECRET,
      redirect_uri: process.env.GOOGLE_REDIRECT_URI,
      refresh_token: process.env.GOOGLE_REFRESH_TOKEN
    });
  }

  // 實現其他工具方法，如 listEvents, createEvent 等
}

構建與運行

npm run build

✨ 主要特性

• list_events：列出指定時間段內的日曆事件
• create_event：創建新的日曆事件
• update_event：更新現有日曆事件
• delete_event：刪除日曆事件
• find_free_time：查找可用的時間段

🔧 技術細節

本項目藉助 Model Context Protocol (MCP) 實現與 Google Calendar 的集成，通過自然語言處理技術，允許用戶在 Claude 中管理和查詢日曆事件。項目使用 Node.js 作為運行環境，依賴 @modelcontextprotocol/sdk、googleapis、google-auth-library 和 zod 等庫。

⚠️ 重要提示

• 確保 OAuth 憑據的安全性，不要將其提交到版本控制系統。
• 定期輪換刷新令牌。
• 監控 Google Cloud Console 中的 API 使用情況。

📚 詳細文檔

如遇問題，請按照以下步驟處理：

1. 參考故障排除部分。
2. 查看 Claude Desktop 日誌。
3. 在 GitHub 上創建問題。
4. 聯繫維護人員。