MCP Google Calendar And Meet

🚀 Google Meet MCP Server v3.0 - 生產就緒版

這是一個適用於企業生產環境的模型上下文協議（MCP）服務器，可通過 Google Calendar API v3 和 Google Meet API v2 全面管理 Google Meet。它具備Docker 容器化、Smithery 部署、直接令牌認證、團隊安全保障等特性，採用企業級 TypeScript 架構，擁有 23 個經過充分驗證的工具。

🚀 快速開始

🔨 Smithery（推薦）

• 適合團隊和個人用戶
• 通過 Web 界面一鍵部署
• 自動更新和健康監控
• 📖 完整的 Smithery 用戶指南

🐳 Docker

• 支持全容器化的生產部署
• 多階段構建，優化大小和安全性
• 提供開發和生產配置
• 📖 Docker 部署指南

⚙️ 手動設置

• 可完全控制安裝和配置
• 適用於開發環境和自定義部署
• 可直接使用 TypeScript 執行 Node.js
• 📖 手動設置指南

🚀 v3.0 生產就緒版的新特性

🎯 v3.0 新特性 - 生產功能

🐳 Docker 容器化

• ✅ 多階段生產構建 - 針對大小和安全性進行優化（<200MB）
• ✅ 使用 Docker Compose 進行開發和生產配置
• ✅ 健康檢查和監控 - 容器原生健康端點
• ✅ 安全強化 - 非根用戶、只讀文件系統
• ✅ 卷管理 - 持久數據和憑證處理

🔨 Smithery 集成 + 直接令牌認證

• ✅ 直接令牌認證 - 無需文件依賴（CLIENT_ID、CLIENT_SECRET、REFRESH_TOKEN）
• ✅ 一鍵部署 - 通過 Web 界面輕鬆配置
• ✅ 向後兼容 - 仍然支持基於文件的 OAuth 憑證
• ✅ 團隊友好設置 - 個人憑證、共享項目結構
• ✅ 自動健康監控 - 即時服務器狀態和指標
• ✅ 跨平臺支持 - 兼容 Windows、macOS、Linux
• ✅ 配置驗證 - 智能路徑處理和錯誤檢測

🛡️ 增強的安全性

• ✅ 團隊安全策略 - 企業級憑證管理
• ✅ 個人憑證隔離 - 用戶之間無共享機密
• ✅ 合規性監控 - 自動安全和輪換跟蹤
• ✅ 審計日誌 - 與 Google Cloud Console 集成
• ✅ 事件響應 - 記錄安全事件處理流程

📚 完整文檔

• ✅ 所有部署方法的用戶指南 - Smithery、Docker、手動
• ✅ 團隊入職流程 - 適用於企業環境的分步指南
• ✅ 故障排除和診斷 - 常見問題和自動解決方案
• ✅ 安全最佳實踐 - 個人和團隊安全策略

📊 生產質量指標

• 容器大小：<200MB 生產鏡像
• 安全評分：非根用戶、最小攻擊面
• 文檔覆蓋率：7 份綜合指南（2000 + 行）
• 部署選項：3 種方法（Smithery、Docker、手動）
• 團隊就緒：多用戶、企業安全、合規性監控

🎯 核心功能 - 增強版

清晰的 API 分離

• 📅 Google Calendar API v3 - 全面的日曆事件管理，支持嘉賓權限設置
• 🎥 Google Meet API v2 (GA) - 空間管理、會議記錄和參會者跟蹤

企業功能

• 📝 自動轉錄 - 開啟會議自動轉錄功能
• 🧠 智能筆記 - 使用 Gemini 生成 AI 會議摘要
• 📊 考勤報告 - 生成詳細的考勤跟蹤報告
• 🛡️ 會議主持 - 聊天/演示限制和控制
• 👀 觀看者模式 - 默認強制參會者以觀看者身份加入
• 📹 自動錄製 - 開啟自動錄製（需手動激活）

高級空間管理

• 🏗️ Google Meet 空間 - 直接創建和配置空間
• 👥 參會者跟蹤 - 訪問參會者數據和會話信息
• 🔒 訪問控制 - 支持 OPEN、TRUSTED 或 RESTRICTED 訪問類型
• ⚙️ 工件配置 - 錄製、轉錄和智能筆記設置

🚀 安裝與部署

🔨 Smithery（推薦用於團隊）

1. 訪問 Smithery.ai
2. 點擊“部署服務器”
3. 配置你的 Google 憑證路徑
4. 在 Claude Desktop 中開始使用

📖 完整的 Smithery 用戶指南 - 團隊分步指南

🐳 Docker（推薦用於生產）

# 快速開始開發
./scripts/docker-deploy.sh dev

# 生產部署
./scripts/docker-deploy.sh prod --backup --fresh

# 查看狀態
./scripts/docker-deploy.sh status

📖 Docker 部署指南 - 全容器化部署

⚙️ 手動安裝

# 克隆倉庫
git clone https://github.com/INSIDE-HAIR/google-meet-mcp-server.git
cd google-meet-mcp-server

# 安裝依賴
npm install

# 設置 OAuth 憑證
npm run setup

📖 手動設置指南 - 完全控制安裝

🛡️ 安全與團隊管理

🔐 個人安全

• 每個用戶創建自己的 Google OAuth 憑證
• 團隊成員之間無共享憑證或令牌
• 使用適當的權限（chmod 600）安全存儲文件
• 📖 安全指南 - 個人安全實踐

👥 團隊安全

• 全面的團隊入職流程
• 企業 Google Cloud 項目管理
• 憑證輪換和合規性監控
• 📖 團隊安全指南 - 企業團隊部署

🔧 故障排除

• 全面的診斷和問題解決
• 常見問題和解決方案
• 健康檢查腳本和監控
• 📖 故障排除指南 - 詳細問題解決

💻 使用示例

開發模式（TypeScript 熱重載）

# 在開發模式下啟動服務器
npm run start

# 在 TypeScript 模式下運行設置
npm run setup

生產模式（編譯後的 JavaScript）

# 將 TypeScript 編譯為 JavaScript
npm run build

# 運行編譯後的服務器
npm run start:js

測試

# 運行所有測試
npm test

# 以監聽模式運行測試
npm run test:watch

# 生成覆蓋率報告
npm run test:coverage

# 僅進行類型檢查
npm run type-check

🛠️ 可用工具（共 21 個） - 全部類型安全且經過驗證

📅 Google Calendar API v3 工具（6 個工具）

1. calendar_v3_list_calendars ✅ 已驗證

列出用戶可用的所有日曆。

驗證：無需參數

2. calendar_v3_list_events ✅ 已驗證

列出即將到來的日曆事件，支持過濾選項。

驗證：日期格式、最大結果數（1 - 2500）、日曆 ID 格式

3. calendar_v3_get_event ✅ 已驗證

獲取特定日曆事件的詳細信息。

驗證：需要 event_id 參數

4. calendar_v3_create_event ✅ 已驗證

創建新的日曆事件，可選擇添加 Google Meet 會議。

驗證：必填字段、ISO 日期格式、嘉賓權限、持續時間邏輯

參數：

• summary（必填）：事件標題
• start_time（必填）：ISO 格式的開始時間
• end_time（必填）：ISO 格式的結束時間
• create_meet_conference（可選）：添加 Google Meet
• guest_can_invite_others（可選）：嘉賓邀請權限
• guest_can_modify（可選）：嘉賓修改權限
• guest_can_see_other_guests（可選）：嘉賓可見權限

5. calendar_v3_update_event ✅ 已驗證

更新現有日曆事件。

驗證：需要 event_id，可選更新字段，時間驗證

6. calendar_v3_delete_event ✅ 已驗證

刪除日曆事件。

驗證：需要 event_id 參數

🎥 Google Meet API v2 工具（15 個工具）

7. meet_v2_create_space ✅ 已驗證

創建具有高級配置的 Google Meet 空間。

驗證：訪問類型枚舉、布爾標誌、限制組合

參數：

• access_type："OPEN" | "TRUSTED" | "RESTRICTED"（默認："TRUSTED"）
• enable_recording：開啟自動錄製準備
• enable_transcription：開啟自動轉錄
• moderation_mode："ON" | "OFF" 會議主持模式
• chat_restriction：聊天權限控制
• present_restriction：演示權限控制

8. meet_v2_get_space ✅ 已驗證

獲取 Google Meet 空間的詳細信息。

驗證：空間名稱格式 (spaces/{space_id})

9. meet_v2_update_space ✅ 已驗證

更新 Google Meet 空間的配置。

10. meet_v2_end_active_conference ✅ 已驗證

結束 Google Meet 空間中的活動會議。

驗證：空間名稱格式驗證

11. meet_v2_list_conference_records ✅ 已驗證

列出歷史會議的會議記錄。

驗證：過濾格式、頁面大小限制（1 - 50）

12 - 21. 其他 Meet API 工具 ✅ 全部已驗證

• meet_v2_get_conference_record - 獲取特定會議的詳細信息
• meet_v2_list_recordings - 列出會議錄製文件
• meet_v2_get_recording - 獲取錄製文件的詳細信息
• meet_v2_list_transcripts - 列出會議轉錄文件
• meet_v2_get_transcript - 獲取轉錄文件的詳細信息
• meet_v2_list_transcript_entries - 列出轉錄語音片段
• meet_v2_get_participant - 獲取參會者的詳細信息
• meet_v2_list_participants - 列出會議參會者
• meet_v2_get_participant_session - 獲取會話的詳細信息
• meet_v2_list_participant_sessions - 列出參會者會話

驗證功能：

• 資源名稱格式驗證（conferenceRecords/{id}/recordings/{id}）
• 頁面大小限制（根據端點不同為 1 - 1000）
• 對所有 Google API 資源標識符進行正則表達式驗證
• 分頁的智能默認設置

MCP 配置（Claude Desktop）

添加到你的 Claude Desktop 配置中：

{
  "mcpServers": {
    "google-meet": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/google-meet-mcp-server/src/index.ts"],
      "env": {
        "G_OAUTH_CREDENTIALS": "/absolute/path/to/credentials.json"
      },
      "disabled": false
    }
  }
}

生產配置（使用編譯後的 JS）：

{
  "mcpServers": {
    "google-meet": {
      "command": "node",
      "args": ["/absolute/path/to/google-meet-mcp-server/build/index.js"],
      "env": {
        "G_OAUTH_CREDENTIALS": "/absolute/path/to/credentials.json"
      },
      "disabled": false
    }
  }
}

🏗️ 企業架構

TypeScript 結構

google-meet-mcp-server/
├── src/
│   ├── index.ts                 # 主 MCP 服務器（TypeScript）
│   ├── GoogleMeetAPI.ts         # API 包裝器（完全類型化）
│   ├── setup.ts                 # OAuth 設置（類型化）
│   ├── types/                   # 類型系統（921 + 行）
│   │   ├── google-apis.d.ts        # Google API 類型
│   │   ├── mcp-server.d.ts         # MCP 特定類型
│   │   ├── utilities.d.ts          # 品牌類型和輔助工具
│   │   └── index.ts                # 集中導出
│   ├── validation/              # Zod 模式
│   │   └── meetSchemas.ts          # 6 個已驗證的工具
│   └── errors/                  # 錯誤處理
│       └── GoogleApiErrorHandler.ts
├── test/                        # 測試套件（101 個測試）
│   ├── setup.ts                    # 測試工具
│   ├── GoogleMeetAPI.test.ts       # 單元測試
│   ├── integration.test.ts         # 集成測試
│   ├── validation.test.ts          # 驗證測試
│   └── simple.test.ts             # 基本功能測試
├── build/                       # 編譯後的 JavaScript
├── package.json                 # TypeScript + 測試依賴
├── tsconfig.json               # TypeScript 配置
└── vitest.config.ts            # 測試配置

類型安全特性

// 增強安全性的品牌類型
type EventId = Brand<string, 'EventId'>;
type SpaceName = Brand<string, 'SpaceName'>;

// 完整的 API 接口
interface GoogleMeetAPI {
  createMeetSpace(config: SpaceConfigInput): Promise<MeetSpace>;
  listCalendars(): Promise<ProcessedCalendar[]>;
  createCalendarEvent(data: CreateEventInput): Promise<ProcessedEvent>;
}

// 帶有業務邏輯的 Zod 驗證
const CreateSpaceSchema = z.object({
  access_type: z.enum(["OPEN", "TRUSTED", "RESTRICTED"]).default("TRUSTED"),
  enable_recording: z.boolean().default(false)
}).refine((data) => {
  // 自定義業務邏輯驗證
  if (data.enable_recording && data.access_type === "OPEN") {
    throw new Error("公開訪問的會議不能啟用錄製功能");
  }
  return true;
});

錯誤處理 - 針對 Claude Desktop 優化

服務器提供了針對 AI 輔助的上下文感知錯誤消息：

Google API 錯誤

🔐 訪問被拒絕
問題：你的 Google 賬戶沒有所需的權限。
解決方案：
1. 運行 `npm run setup` 重新進行身份驗證
2. 確保你授予了所有請求的權限
3. 對於企業功能，請確保你擁有 Google Workspace Business+ 套餐

企業功能錯誤

🏢 需要企業功能
問題：此 Meet 功能需要 Google Workspace Business Standard 或更高版本。
選項：
- 改為使用帶有 Meet 鏈接的基本日曆事件
- 升級你的 Google Workspace 套餐
替代方案：嘗試使用 `calendar_v3_create_event` 並設置 `create_meet_conference: true`

要求

技術要求

• Node.js：18+（支持 TypeScript）
• TypeScript：5+（包含在依賴項中）
• Google 賬戶：任何 Google 賬戶均可使用基本功能

功能要求

• ✅ 基本功能：任何 Google 賬戶均可使用
• ✅ 日曆集成：需啟用 Google Calendar API
• 🏢 企業功能：需要 Google Workspace Business Standard 或更高版本
• 🧠 智能筆記：需要 Gemini Business/Enterprise 許可證
• 📹 錄製：會議期間需要手動激活

開發

TypeScript 開發

# 開發時熱重載
npm run start          # 使用 watch 模式運行 tsx src/index.ts
npm run setup          # 運行 tsx src/setup.ts

# 類型檢查
npm run type-check     # 運行 tsc --noEmit

# 測試
npm test              # 運行 vitest
npm run test:watch    # 以監聽模式運行 vitest
npm run test:coverage # 生成覆蓋率報告

生產構建

# 編譯 TypeScript
npm run build         # 編譯到 build/ 目錄
npm run clean         # 清理 build 目錄

# 運行編譯後的 JavaScript
npm run start:js      # 運行 node build/index.js
npm run setup:js      # 運行 node build/setup.js

測試結果

✅ 測試文件：5 個通過（共 5 個）
✅ 測試用例：101 個通過（共 101 個）
✅ 持續時間：2.61 秒
✅ TypeScript：0 個編譯錯誤
✅ 類型覆蓋率：約 90% 特定類型

測試類別：
- 28 個 GoogleMeetAPI 單元測試
- 12 個集成工作流測試
- 35 個驗證模式測試
- 16 個基本功能測試
- 10 個 MCP 服務器測試

🔧 常見問題與快速修復

🚨 服務器無法啟動

# 檢查憑證路徑和權限
ls -la "/path/to/your/credentials.json"
chmod 600 "/path/to/your/credentials.json"

# 驗證配置
npx tsx scripts/health-check.js

🔐 身份驗證失敗

# 重新運行 OAuth 設置
G_OAUTH_CREDENTIALS="/path/to/creds.json" npm run setup

# 檢查 Google Cloud Console：
# 1. 啟用的 API（Calendar + Meet）
# 2. 配置的 OAuth 同意屏幕
# 3. 正確設置的範圍

🤖 Claude Desktop 問題

# 驗證 MCP 配置
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 重啟 Claude Desktop
# 檢查 Smithery 中的服務器狀態（如果使用）

📖 完整的故障排除指南 - 詳細的問題解決方法

企業功能限制

Google Meet API v2

• 一些高級功能需要 Google Workspace 許可證
• 無法通過編程方式啟動錄製（需要手動激活）
• 智能筆記需要 Gemini Business/Enterprise 許可證
• 參會者數據僅在會議結束後可用

實現說明

• 所有 21 個工具均使用官方 Google API 完全實現
• 高級功能使用直接 REST API 調用 Google Meet API v2
• 自動處理身份驗證和令牌管理
• 完整的 TypeScript 覆蓋，使用品牌類型確保安全

🤝 貢獻

開發要求

• ✅ TypeScript 代碼：具有正確的類型（無 'any' 類型）
• ✅ 測試通過 (npm test) - 保持 100% 測試成功率
• ✅ 新工具的 Zod 驗證模式
• ✅ 新端點的錯誤處理
• ✅ 新功能的文檔更新
• ✅ 憑證處理的安全審查

貢獻流程

1. 分叉並克隆 倉庫
2. 從 main 分支 創建功能分支
3. 實現更改，並添加測試和文檔
4. 運行完整測試套件 (npm test)
5. 更新 docs/ 中的相關指南
6. 提交拉取請求，並提供詳細描述

📄 許可證

ISC 許可證 - 可免費用於商業和個人用途。詳情請參閱 LICENSE 文件。

---

🎉 準備好提升你的 Google Meet 工作流程了嗎？選擇上述部署方法，幾分鐘內即可開始使用！

💡 推薦：從 Smithery 部署 開始，體驗最簡單的設置過程。

📞 支持與資源

📚 文檔

• Smithery 用戶指南 - 使用 Smithery 進行團隊部署
• Docker 部署指南 - 容器化生產部署
• 手動設置指南 - 直接安裝和配置
• 安全指南 - 個人安全最佳實踐
• 團隊安全指南 - 企業團隊管理
• 故障排除指南 - 問題診斷和解決

🆘 獲取幫助

• 🐛 GitHub 問題 - 提交 bug 報告和功能請求
• 🔨 Smithery 支持 - 平臺特定幫助
• 📖 MCP 文檔 - 模型上下文協議資源

🎯 快速鏈接

• 倉庫：github.com/INSIDE-HAIR/google-meet-mcp-server
• Smithery 頁面：smithery.ai/server/@inside-hair/google-meet-mcp-server
• Docker Hub：ghcr.io/inside-hair/google-meet-mcp-server

致謝

• 基於 Model Context Protocol SDK 構建
• 由 Google Calendar API 和 Google Meet API 提供支持
• 與 Claude Desktop 和其他 MCP 客戶端兼容
• 採用企業級 TypeScript 架構
• 擁有全面的 Zod 驗證系統