Google Workspace MCP

🚀 Google Workspace MCP Server

這是功能最齊全的 Google Workspace MCP 服務器，現在支持一鍵安裝 Claude。通過所有 MCP 客戶端、AI 助手和開發工具，可對 Google Calendar、Drive、Gmail、Docs、Sheets、Slides、Forms、Tasks 和 Chat 進行全自然語言控制。支持所有免費 Google 賬戶（Gmail、Docs、Drive 等）和 Google Workspace 計劃（Starter、Standard、Plus、Enterprise、Non Profit 等）及其擴展應用選項，如 Chat 和 Spaces。

項目演示

AI 輔助編寫說明

🚀 快速開始

1. 一鍵安裝 Claude Desktop（推薦）

1. 下載：從“Releases”頁面獲取最新的 google_workspace_mcp.dxt 文件。
2. 安裝：雙擊該文件，Claude Desktop 會打開並提示你點擊“安裝”。
3. 配置：在 Claude Desktop 中，依次點擊 Settings → Extensions → Google Workspace MCP，粘貼你的 Google OAuth 憑證。
4. 使用：開啟一個新的 Claude 聊天窗口，即可調用任何 Google Workspace 工具。

⚠️ 重要提示

為何使用 DXT 文件？桌面擴展（.dxt）將服務器、依賴項和清單文件打包在一起，用戶只需一鍵操作，即可從下載完成到讓 MCP 正常運行，無需使用終端、編輯 JSON 文件，也不會出現版本衝突問題。

必要配置

2. 高級/跨平臺安裝

如果你是進行開發、部署到服務器，或者使用其他支持 MCP 的客戶端，請繼續閱讀以下內容。

即時命令行安裝（uvx）

# 需要 Python 3.11+ 和 uvx
export GOOGLE_OAUTH_CLIENT_ID="xxx"
export GOOGLE_OAUTH_CLIENT_SECRET="yyy"
uvx workspace-mcp --tools gmail drive calendar

⚠️ 重要提示

使用 uvx 時可立即運行，無需手動安裝，但你必須配置 OAuth 憑證。你可以使用環境變量（推薦用於生產環境），也可以設置 GOOGLE_CLIENT_SECRET_PATH（或舊版的 GOOGLE_CLIENT_SECRETS）環境變量，指向你的 client_secret.json 文件。

# 通過環境變量設置 OAuth 憑證（推薦）
export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"

# 啟動包含所有 Google Workspace 工具的服務器
uvx workspace-mcp

# 僅啟動特定工具
uvx workspace-mcp --tools gmail drive calendar tasks

# 以 HTTP 模式啟動，用於調試
uvx workspace-mcp --transport streamable-http

此安裝方式需要 Python 3.11+ 和 uvx。該軟件包可在 PyPI 上獲取。

開發環境安裝

若你需要進行開發或定製：

git clone https://github.com/taylorwilsdon/google_workspace_mcp.git
cd google_workspace_mcp
uv run main.py

前提條件

• Python 3.11+
• uvx（用於即時安裝）或 uv（用於開發）
• 擁有 OAuth 2.0 憑證的 Google Cloud 項目

配置

Google Cloud 設置

• 在 Google Cloud Console 中創建 OAuth 2.0 憑證（Web 應用程序）。
• 啟用以下 API：Calendar、Drive、Gmail、Docs、Sheets、Slides、Forms、Tasks、Chat。
• 添加重定向 URI：http://localhost:8000/oauth2callback。
• 可使用以下方法之一配置憑證：

選項 A：環境變量（推薦用於生產環境）

export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:8000/oauth2callback"  # 可選

選項 B：基於文件（傳統方式）

• 將憑證下載為 client_secret.json 文件，放在項目根目錄下。
• 若要使用其他位置的文件，可設置 GOOGLE_CLIENT_SECRET_PATH（或舊版的 GOOGLE_CLIENT_SECRETS）環境變量，指定文件路徑。

憑證加載優先級：

1. 環境變量（GOOGLE_OAUTH_CLIENT_ID、GOOGLE_OAUTH_CLIENT_SECRET）
2. GOOGLE_CLIENT_SECRET_PATH 或 GOOGLE_CLIENT_SECRETS 環境變量指定的文件
3. 默認文件（項目根目錄下的 client_secret.json）

💡 使用建議

為何推薦使用環境變量？

• ✅ 適用於容器化部署（Docker、Kubernetes）
• ✅ 適用於雲平臺（Heroku、Railway 等）
• ✅ 適用於 CI/CD 管道
• ✅ 不會將機密信息存儲在版本控制系統中
• ✅ 便於憑證輪換

環境配置

export OAUTHLIB_INSECURE_TRANSPORT=1  # 僅用於開發環境
export USER_GOOGLE_EMAIL=your.email@gmail.com  # 可選：認證的默認電子郵件 - 用於單用戶設置，使用此選項後，在系統提示中進行魔法認證時無需設置電子郵件

服務器配置

可使用環境變量自定義服務器的基本 URL 和端口：

• WORKSPACE_MCP_BASE_URI：設置服務器的基本 URI（默認：http://localhost）。如果未設置 GOOGLE_OAUTH_REDIRECT_URI，此設置將影響用於構建默認 OAUTH_REDIRECT_URI 的 server_url。
• WORKSPACE_MCP_PORT：設置服務器監聽的端口（默認：8000）。此設置將影響 server_url、端口和 OAUTH_REDIRECT_URI。
• USER_GOOGLE_EMAIL：可選的認證流程默認電子郵件。如果設置了此選項，大語言模型在調用 start_google_auth 時無需指定你的電子郵件。
• GOOGLE_OAUTH_REDIRECT_URI：專門為 OAuth 重定向設置覆蓋值，必須包含完整地址（如有必要，需包含端口）。僅在非常特殊的情況下推薦使用此選項，用於將 OAuth 重定向與 MCP 分開運行。

啟動服務器

# 默認（MCP 客戶端的標準輸入輸出模式）
uv run main.py

# HTTP 模式（用於 Web 界面和調試）
uv run main.py --transport streamable-http

# 單用戶模式（簡化認證）
uv run main.py --single-user

# 選擇性工具註冊（僅註冊特定工具）
uv run main.py --tools gmail drive calendar tasks
uv run main.py --tools sheets docs
uv run main.py --single-user --tools gmail  # 可與其他標誌組合使用

# Docker 方式
docker build -t workspace-mcp .
docker run -p 8000:8000 -v $(pwd):/app workspace-mcp --transport streamable-http

--tools 標誌可用工具：gmail、drive、calendar、docs、sheets、forms、tasks、chat

連接到 Claude Desktop

服務器支持兩種傳輸模式：

標準輸入輸出模式（默認 - 推薦用於 Claude Desktop）

引導式設置（若不使用 DXT，推薦此方式）

python install_claude.py

此腳本會自動執行以下操作：

• 提示你輸入 Google OAuth 憑證（客戶端 ID 和密鑰）
• 在正確的位置創建 Claude Desktop 配置文件
• 設置所有必要的環境變量
• 無需手動編輯文件！

運行腳本後，重啟 Claude Desktop 即可使用。

手動配置 Claude（替代方法）

1. 打開 Claude Desktop 設置 → 開發者 → 編輯配置
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
2. 添加服務器配置：

{
  "mcpServers": {
    "google_workspace": {
      "command": "uvx",
      "args": ["workspace-mcp"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
        "OAUTHLIB_INSECURE_TRANSPORT": "1"
      }
    }
  }
}

獲取 Google OAuth 憑證（若你沒有）：

• 訪問 Google Cloud Console
• 創建一個新項目並啟用以下 API：Calendar、Drive、Gmail、Docs、Sheets、Slides、Forms、Tasks、Chat
• 創建 OAuth 2.0 客戶端 ID（Web 應用程序），重定向 URI 為：http://localhost:8000/oauth2callback

開發環境安裝（適用於貢獻者）：

{
  "mcpServers": {
    "google_workspace": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/repo/google_workspace_mcp",
        "main.py"
      ],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
        "OAUTHLIB_INSECURE_TRANSPORT": "1"
      }
    }
  }
}

HTTP 模式（用於調試或 Web 界面）

若你需要在 Claude Desktop 中使用 HTTP 模式：

{
  "mcpServers": {
    "google_workspace": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8000/mcp"]
    }
  }
}

⚠️ 重要提示

使用 HTTP 模式時，務必使用 --transport streamable-http 啟動服務器。

首次認證

服務器具備傳輸感知的 OAuth 回調處理功能：

• 標準輸入輸出模式：自動在端口 8000 上啟動一個最小的 HTTP 服務器，用於 OAuth 回調。
• HTTP 模式：使用現有的 FastAPI 服務器進行 OAuth 回調。
• 相同的 OAuth 流程：兩種模式均使用 http://localhost:8000/oauth2callback 以保持一致性。

調用工具時：

1. 服務器返回授權 URL。
2. 在瀏覽器中打開該 URL 並授權。
3. 服務器會自動處理 OAuth 回調（兩種模式均在端口 8000 上）。
4. 重試原始請求。

✨ 主要特性

• 🔐 高級 OAuth 2.0：安全認證，具備自動令牌刷新、傳輸感知回調處理、會話管理和集中式範圍管理功能。
• 📅 Google Calendar：完整的日曆管理，支持事件的創建、讀取、更新和刪除操作。
• 📁 Google Drive：文件操作，支持原生 Microsoft Office 格式（.docx、.xlsx）。
• 📧 Gmail：完整的電子郵件管理，具備搜索、發送和草稿功能。
• 📄 Google Docs：文檔操作，包括內容提取、創建和評論管理。
• 📊 Google Sheets：全面的電子表格管理，支持靈活的單元格操作和評論管理。
• 🖼️ Google Slides：演示文稿管理，支持幻燈片創建、更新、內容操作和評論管理。
• 📝 Google Forms：表單創建、檢索、發佈設置和響應管理。
• ✓ Google Tasks：完整的任務和任務列表管理，支持層次結構、截止日期和狀態跟蹤。
• 💬 Google Chat：空間管理和消息傳遞功能。
• 🔄 全傳輸方式支持：標準輸入輸出、可流式傳輸的 HTTP 和 Server-Sent Events（SSE），通過 mcpo 實現 OpenAPI 兼容性。
• ⚡ 高性能：服務緩存、線程安全會話、集成 FastMCP。
• 🧩 開發者友好：最少的樣板代碼、自動服務注入、集中式配置。

🧰 可用工具

⚠️ 重要提示

所有工具都支持通過 @require_google_service() 裝飾器進行自動認證，並具備 30 分鐘的服務緩存。

📅 Google Calendar ()

📁 Google Drive ()

📧 Gmail ()

📝 Google Docs ()

📊 Google Sheets ()

🖼️ Google Slides ()

📝 Google Forms ()

✓ Google Tasks ()

💬 Google Chat ()

🛠️ 開發

項目結構

google_workspace_mcp/
├── auth/              # 帶有裝飾器的認證系統
├── core/              # MCP 服務器和實用工具
├── g{service}/        # 特定服務的工具
├── main.py            # 服務器入口點
├── client_secret.json # OAuth 憑證（不提交到版本控制）
└── pyproject.toml     # 依賴項

添加新工具

from auth.service_decorator import require_google_service

@require_google_service("drive", "drive_read")  # 服務 + 範圍組
async def your_new_tool(service, param1: str, param2: int = 10):
    """工具描述"""
    # 服務會自動注入並緩存
    result = service.files().list().execute()
    return result  # 返回原生 Python 對象

架構亮點

• 服務緩存：30 分鐘的 TTL 可減少認證開銷。
• 範圍管理：集中在 SCOPE_GROUPS 中，便於維護。
• 錯誤處理：使用原生異常，而非手動構建錯誤。
• 多服務支持：@require_multiple_services() 適用於複雜工具。

🔧 技術細節

這是一個生產就緒的 MCP 服務器，將所有主要的 Google Workspace 服務與 AI 助手集成。使用 FastMCP 構建以實現最佳性能，具備高級認證處理、服務緩存和簡化的開發模式。

🔒 安全

• 憑證管理：切勿將 client_secret.json 或 .credentials/ 目錄提交到版本控制中。
• OAuth 回調：開發環境使用 http://localhost:8000/oauth2callback（需要 OAUTHLIB_INSECURE_TRANSPORT=1）。
• 傳輸感知回調：標準輸入輸出模式僅為 OAuth 啟動一個最小的 HTTP 服務器，確保在所有模式下回調都能正常工作。
• 生產環境：回調 URI 使用 HTTPS 並進行相應配置。
• 網絡暴露：通過網絡使用 mcpo 時，需考慮認證問題。
• 範圍最小化：工具僅請求必要的權限。

🌐 與 Open WebUI 集成

若要在 Open WebUI 中使用此服務器作為工具提供者：

即時啟動（無需配置）

只需複製粘貼以下內容，設置好值即可開始使用！

GOOGLE_OAUTH_CLIENT_ID="your_client_id" GOOGLE_OAUTH_CLIENT_SECRET="your_client_secret" uvx mcpo --port 8000 --api-key "top-secret" -- uvx workspace-mcp

手動配置步驟

1. 創建 MCPO 配置

創建一個名為 config.json 的文件，使用以下結構，使 mcpo 將可流式傳輸的 HTTP 端點作為 OpenAPI 規範工具提供：

{
  "mcpServers": {
    "google_workspace": {
      "type": "streamablehttp",
      "url": "http://localhost:8000/mcp"
    }
  }
}

2. 啟動 MCPO 服務器

mcpo --port 8001 --config config.json --api-key "your-optional-secret-key"

此命令將啟動 mcpo 代理，在端口 8001 上提供你的 Google Workspace MCP 服務（假設端口 8000 上的服務已啟動）。

3. 配置 Open WebUI

1. 導航到你的 Open WebUI 設置。
2. 轉到 "連接" → "工具"。
3. 點擊 "添加工具"。
4. 輸入 服務器 URL：http://localhost:8001/google_workspace（與 config.json 中的 mcpo 基本 URL 和服務器名稱匹配）。
5. 若你在 mcpo 中使用了 --api-key，請將其作為 API 密鑰輸入。
6. 保存配置。

配置完成後，在 Open WebUI 中與模型交互時，Google Workspace 工具應即可使用。

📄 許可證

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