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 輔助編寫說明

為何使用 AI 輔助？

本 README 由 AI 輔助編寫，原因如下：作為一名獨立開發者，開發的開源工具可能鮮有人使用，若沒有 AI 幫助，全面的文檔往往難以完成。使用像 Roo 和 Claude Code 這類能理解整個代碼庫的智能開發工具，AI 並非只是生成通用內容，而是提取實際的實現細節，創建準確、具體的文檔。在這個案例中，Sonnet 4 參與編寫，人類（即我）於 2025 年 7 月 10 日進行了審核。

🚀 快速開始

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 文件，也不會出現版本衝突問題。

必要配置

環境配置 - 你將在 Claude 中進行配置，詳見截圖：

變量	用途
GOOGLE_OAUTH_CLIENT_ID	從 Google Cloud 獲取的 OAuth 客戶端 ID
GOOGLE_OAUTH_CLIENT_SECRET	OAuth 客戶端密鑰
USER_GOOGLE_EMAIL（可選）	單用戶認證的默認電子郵件
OAUTHLIB_INSECURE_TRANSPORT=1	僅用於開發環境（允許 http:// 重定向）

Claude Desktop 會將這些信息安全地存儲在操作系統的鑰匙串中，你只需在擴展面板中設置一次即可。

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 ()

工具	描述
list_calendars	列出可訪問的日曆
get_events	按時間範圍過濾檢索事件
get_event	通過 ID 獲取單個事件的詳細信息
create_event	創建事件（全天或定時），可選擇附加 Drive 文件
modify_event	更新現有事件
delete_event	刪除事件

📁 Google Drive ()

工具	描述
search_drive_files	使用查詢語法搜索文件
get_drive_file_content	讀取文件內容（支持 Office 格式）
list_drive_items	列出文件夾內容
create_drive_file	創建新文件或從公共 URL 獲取內容

📧 Gmail ()

工具	描述
search_gmail_messages	使用 Gmail 操作符搜索郵件
get_gmail_message_content	檢索郵件內容
send_gmail_message	發送郵件
draft_gmail_message	創建草稿

📝 Google Docs ()

工具	描述
search_docs	按名稱查找文檔
get_doc_content	提取文檔文本
list_docs_in_folder	列出文件夾中的文檔
create_doc	創建新文檔
read_doc_comments	讀取所有評論和回覆
create_doc_comment	創建新評論
reply_to_comment	回覆現有評論
resolve_comment	解決評論

📊 Google Sheets ()

工具	描述
list_spreadsheets	列出可訪問的電子表格
get_spreadsheet_info	獲取電子表格元數據
read_sheet_values	讀取單元格範圍
modify_sheet_values	寫入/更新/清除單元格
create_spreadsheet	創建新電子表格
create_sheet	向現有文件中添加工作表
read_sheet_comments	讀取所有評論和回覆
create_sheet_comment	創建新評論
reply_to_sheet_comment	回覆現有評論
resolve_sheet_comment	解決評論

🖼️ Google Slides ()

工具	描述
create_presentation	創建新演示文稿
get_presentation	檢索演示文稿詳細信息
batch_update_presentation	一次性應用多個更新
get_page	獲取特定幻燈片信息
get_page_thumbnail	生成幻燈片縮略圖
read_presentation_comments	讀取所有評論和回覆
create_presentation_comment	創建新評論
reply_to_presentation_comment	回覆現有評論
resolve_presentation_comment	解決評論

📝 Google Forms ()

工具	描述
create_form	創建帶有標題和描述的新表單
get_form	檢索表單詳細信息、問題和 URL
set_publish_settings	配置表單模板和認證設置
get_form_response	獲取單個表單響應的詳細信息
list_form_responses	分頁列出表單的所有響應

✓ Google Tasks ()

工具	描述
list_task_lists	分頁列出所有任務列表
get_task_list	檢索特定任務列表的詳細信息
create_task_list	創建帶有自定義標題的新任務列表
update_task_list	修改現有任務列表的標題
delete_task_list	刪除任務列表及其中包含的所有任務
list_tasks	按過濾選項列出特定列表中的任務
get_task	檢索特定任務的詳細信息
create_task	創建帶有標題、備註、截止日期和層次結構的新任務
update_task	修改任務屬性，包括標題、備註、狀態和截止日期
delete_task	從任務列表中刪除任務
move_task	在列表中重新定位任務或在列表之間移動任務
clear_completed_tasks	隱藏列表中所有已完成的任務

💬 Google Chat ()

工具	描述
list_spaces	列出聊天空間/房間
get_messages	檢索空間消息
send_message	向空間發送消息
search_messages	在聊天曆史記錄中搜索

🛠️ 開發

項目結構

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 文件。