Skip to content

Latest commit

 

History

History
333 lines (252 loc) · 10.5 KB

README.zh-TW.md

File metadata and controls

333 lines (252 loc) · 10.5 KB

Google Workspace MCP Server

License: MIT TypeScript Node.js MCP

English | 简体中文 | 繁體中文

一個全面的 MCP (Model Context Protocol) 伺服器,提供完整的 Google Workspace 整合 - 包括 Google Docs、Sheets、Drive、Gmail、Calendar 和 Apps Script API。相容 Claude Code CLI、Cursor IDE 及其他 MCP 用戶端。

獨特功能: 這是唯一支援 Apps Script API 的 Google Workspace MCP 伺服器 - 實現 AI 驅動的 Google Sheets、Docs 及其他 Workspace 產品自動化。

展示動畫

功能特性

本伺服器提供 72 個工具,涵蓋 6 個 Google Workspace 服務:

服務 工具數 描述
Google Docs 15 讀取、寫入、格式化、樣式、圖片、表格、評論
Google Sheets 14 讀取、寫入、格式化、建立試算表、管理工作表
Google Drive 16 列出、搜尋、建立、移動、複製、刪除檔案和資料夾
Gmail 15 搜尋、閱讀、傳送、草稿、標籤、篩選器、對話
Google Calendar 8 日曆清單、活動、建立、更新、刪除、空閒/忙碌
Apps Script 4 建立和管理繫結指令碼以實現自動化

Google Docs (15 個工具)

  • 文件操作: readGoogleDoc、appendToGoogleDoc、insertText、deleteRange、listDocumentTabs
  • 格式化: applyTextStyle、applyParagraphStyle、formatMatchingText、fixListFormatting
  • 結構: insertTable、editTableCell、insertPageBreak、findElement
  • 圖片: insertImageFromUrl、insertLocalImage

Google Docs 評論 (6 個工具)

  • 評論管理: listComments、getComment、addComment、replyToComment、resolveComment、deleteComment

Google Sheets (14 個工具)

  • 資料操作: readSpreadsheet、writeSpreadsheet、appendSpreadsheetRows、clearSpreadsheetRange
  • 工作表管理: getSpreadsheetInfo、addSpreadsheetSheet、createSpreadsheet、listGoogleSheets
  • 格式化: formatSpreadsheetCells、setBasicFilter、clearBasicFilter

Google Drive (16 個工具)

  • 探索: listGoogleDocs、searchGoogleDocs、getRecentGoogleDocs、getDocumentInfo
  • 資料夾: createFolder、listFolderContents、getFolderInfo
  • 檔案操作: moveFile、copyFile、renameFile、deleteFile
  • 建立: createDocument、createFromTemplate

Apps Script (4 個工具)

  • 指令碼管理: createBoundScript、updateScriptContent、getScriptContent、getScriptProjects

Gmail (15 個工具)

  • 訊息: searchGmailMessages、getGmailMessage、getGmailMessagesBatch、getGmailAttachment
  • 傳送與草稿: sendGmailMessage、createGmailDraft
  • 對話: getGmailThread
  • 標籤: listGmailLabels、createGmailLabel、deleteGmailLabel、modifyGmailMessageLabels
  • 篩選器: listGmailFilters、createGmailFilter、deleteGmailFilter
  • 管理: trashGmailMessage

Google Calendar (8 個工具)

  • 日曆: listCalendars
  • 活動: getCalendarEvents、getCalendarEvent、createCalendarEvent、updateCalendarEvent、deleteCalendarEvent
  • 快捷操作: quickAddCalendarEvent
  • 可用性: getCalendarFreeBusy

前置需求

  • Node.js v18+ 及 npm
  • Git 用於複製儲存庫
  • Google 帳號 具有 Google Workspace 存取權限
  • MCP 相容用戶端: Claude Code CLI、Cursor IDE 或其他 MCP 用戶端

快速開始

方式 A: 互動式安裝精靈 (推薦)

git clone https://github.com/sputnicyoji/google-docs-mcp-for-claudecode.git
cd google-docs-mcp-for-claudecode
npm install
npm run setup

安裝精靈將自動:

  • 檢查環境 (Node.js、npm、建置狀態)
  • 如需要則自動編譯 TypeScript
  • 引導您完成憑證設定
  • 執行 OAuth 授權流程
  • 產生並可選擇自動更新 Claude Code CLI 設定

方式 B: 手動設定

1. 複製並安裝

git clone https://github.com/sputnicyoji/google-docs-mcp-for-claudecode.git
cd google-docs-mcp-for-claudecode
npm install
npm run build

2. Google Cloud 設定

  1. 前往 Google Cloud Console
  2. 建立新專案或選擇現有專案
  3. 啟用以下 API:
    • Google Docs API
    • Google Sheets API
    • Google Drive API
    • Apps Script API
    • Gmail API
    • Google Calendar API
  4. 設定 OAuth 同意畫面:
    • 選擇「外部」使用者類型
    • 新增所需範圍: documents、spreadsheets、drive.file、script.projects、gmail、calendar
    • 將您的電子郵件新增為測試使用者
  5. 建立 OAuth 憑證:
    • 前往 憑證 > 建立憑證 > OAuth 用戶端 ID
    • 選擇「桌面應用程式」
    • 下載 JSON 檔案並另存為專案根目錄的 credentials.json

3. 驗證

node ./dist/server.js

按照終端機中的 URL 授權存取。授權後將建立 token.json。

4. 設定 Claude Code CLI

新增至您的 Claude Code MCP 設定:

Windows (%APPDATA%\Claude\mcp_config.json):

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["C:\\path\\to\\google-docs-mcp-for-claudecode\\dist\\server.js"]
    }
  }
}

macOS/Linux (~/.config/Claude/mcp_config.json):

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/path/to/google-docs-mcp-for-claudecode/dist/server.js"]
    }
  }
}

5. 設定 Cursor IDE (可選)

本 MCP 伺服器完全相容 Cursor IDE。

專案級設定 - 在專案根目錄建立 .cursor/mcp.json:

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/path/to/google-docs-mcp-for-claudecode/dist/server.js"]
    }
  }
}

全域設定 - 或透過 Cursor 設定 > MCP 進行設定。

注意: Cursor 必須處於 Agent 模式 (而非 Ask 模式) 才能存取 MCP 工具。

服務帳號驗證 (替代方案)

對於自動化/伺服器環境,可以使用服務帳號:

  1. 在 Google Cloud Console 中建立服務帳號
  2. 下載 JSON 金鑰檔案
  3. 設定環境變數: 
    export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
  4. 將您的 Google Docs/Sheets 與服務帳號電子郵件共用

使用範例

Google Docs

讀取文件 1abc...xyz 並以 markdown 格式傳回
向文件 1abc...xyz 附加「會議記錄」
對文件 1abc...xyz 中的「重要」文字套用粗體格式
在文件 1abc...xyz 的索引 100 處插入 3x4 表格

Google Sheets

從試算表 1abc...xyz 讀取範圍 A1:D10
向試算表 1abc...xyz 的範圍 A1:B5 寫入資料
建立標題為「2024年銷售報告」的新試算表
向試算表 1abc...xyz 新增名為「摘要」的新工作表

Google Drive

列出我的 Drive 中的所有 Google Docs
搜尋包含「專案 Alpha」的文件
建立名為「2024 報告」的新資料夾
將檔案 1abc...xyz 移動到資料夾 2def...uvw

Apps Script

為試算表 1abc...xyz 建立繫結指令碼
使用自訂函式更新指令碼內容
取得指令碼專案 1abc...xyz 的內容

Gmail

搜尋來自 john@example.com 的未讀郵件
閱讀 ID 為 abc123 的郵件訊息
傳送郵件給 jane@example.com,主旨為「會議」
為對話 xyz789 建立草稿回覆
列出所有 Gmail 標籤
建立篩選器,為來自 support@example.com 的郵件新增標籤

Google Calendar

列出我的所有日曆
取得本週主日曆的活動
建立明天上午10點的「團隊站會」會議
快速新增活動「週五中午和 Sarah 吃午餐」
查看下週一的空閒/忙碌時間
從我的日曆中刪除活動 abc123

專案結構

google-docs-mcp-for-claudecode/
  src/
    server.ts              # 主 MCP 伺服器 (工具定義)
    clients.ts             # Google API 用戶端管理
    auth.ts                # OAuth 2.0 / 服務帳號驗證
    types.ts               # TypeScript 型別定義
    helpers/
      markdown.ts          # Docs 轉 Markdown 轉換
      index.ts             # Helper 重新匯出
    tools/
      scriptTools.ts       # Apps Script 工具
      gmailTools.ts        # Gmail 工具
      calendarTools.ts     # Calendar 工具
      index.ts             # 工具註冊表
    googleDocsApiHelpers.ts    # Docs API 輔助函式
    googleSheetsApiHelpers.ts  # Sheets API 輔助函式
    gmailApiHelpers.ts         # Gmail API 輔助函式
    calendarApiHelpers.ts      # Calendar API 輔助函式
  dist/                    # 編譯後的 JavaScript
  credentials.json         # OAuth 憑證 (不提交)
  token.json               # 驗證權杖 (不提交)

安全注意事項

  • 切勿將 credentials.json 或 token.json 提交到版本控制
  • .gitignore 檔案已設定為排除敏感檔案
  • 對於正式環境,請考慮使用密鑰管理服務
  • 服務帳號金鑰應安全儲存

已知限制

  • 評論錨定: 透過程式建立的評論可能顯示「原始內容已刪除」,而非錨定到特定文字
  • 轉換的文件: 從其他格式 (如 Word) 轉換的某些文件可能不支援所有 API 操作
  • 配額限制: Google API 有使用配額 - 請在 Google Cloud Console 查看限制

疑難排解

連線問題

  1. 驗證 mcp_config.json 中的路徑是絕對路徑且正確
  2. 確保 npm run build 成功完成
  3. 手動測試: node ./dist/server.js

驗證錯誤

  1. 驗證所有必要的 API 已啟用
  2. 檢查您的電子郵件是否已新增為測試使用者
  3. 如果範圍已變更,請刪除 token.json 並重新驗證

分頁/工作表錯誤

  1. 使用 listDocumentTabs 或 getSpreadsheetInfo 驗證 ID
  2. 確保使用正確的 ID 格式

貢獻

歡迎貢獻! 請:

  1. Fork 儲存庫
  2. 建立功能分支
  3. 提交 Pull Request

致謝

基於 a-bonus/google-docs-mcp 進行增強:

  • Google Apps Script API 整合
  • Gmail 和 Google Calendar API 整合
  • 服務帳號驗證支援
  • 模組化程式碼架構
  • 多語言文件

授權條款

MIT 授權條款 - 詳見 LICENSE。