Skip to content

Latest commit

 

History

History
333 lines (252 loc) · 10.4 KB

README.zh-CN.md

File metadata and controls

333 lines (252 loc) · 10.4 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。