gworkspace-mcp

用于 Google Workspace 自动化的模型上下文协议 (MCP) 服务器：支持 Google Sheets、Apps Script、Drive、Docs、Gmail 和触发器。基于 FastMCP 构建。

专为 Claude Code（或任何兼容 MCP 的客户端）设计，让您可以直接在对话中编辑 Apps Script 项目、操作电子表格、发送电子邮件和管理 Drive 文件。

功能

• Apps Script (9 个工具) — 列出、读取、更新、创建、部署和运行 Apps Script 项目。支持细粒度的文件编辑，无需重写整个脚本。

• Sheets (10 个工具) — 读取/写入范围、批量更新、格式设置、保护、公式、仪表板。

• Drive (4 个工具) — 列出、搜索、移动和管理文件。

• Docs (1 个工具) — 读取/编辑 Google Docs。

• Gmail (3 个工具) — 撰写并发送电子邮件。

• Triggers (3 个工具) — 管理 Apps Script 基于时间和事件的触发器。

• Connect (1 个工具) — 将本地 Apps Script 项目绑定到电子表格。

要求

• Python 3.10+

• 一个已启用以下 API 的 Google Cloud 项目：

  • Google Sheets API

  • Google Drive API

  • Apps Script API

  • Google Docs API

  • Gmail API

  • Google Calendar API

• OAuth 2.0 桌面凭据 (client_secret.json)

安装

git clone https://github.com/LeooNic/gworkspace-mcp.git
cd gworkspace-mcp
pip install -e .

或者使用 uv：

uv pip install -e .

Google Cloud 设置

1. 前往 console.cloud.google.com 并创建一个项目。

2. 在 API 和服务 → 库 下启用上述 API。

3. 前往 API 和服务 → OAuth 同意屏幕，将其配置为 外部 (External)，并将您的 Google 帐户添加为测试用户。

4. 前往 API 和服务 → 凭据 → 创建凭据 → OAuth 客户端 ID，选择 桌面应用 (Desktop app)，然后下载 JSON 文件。

5. 通过以下方式之一使凭据对服务器可用：

   • 将 JSON 文件放置在 ~/.secrets/gworkspace-mcp/client_secret.json，或者

   • 设置 GOOGLE_CLIENT_SECRET_PATH=/full/path/to/client_secret.json，或者

   • 将 GOOGLE_OAUTH_CLIENT_ID 和 GOOGLE_OAUTH_CLIENT_SECRET 设置为环境变量。

首次运行工具时，将打开一个浏览器窗口以进行 OAuth 同意。生成的令牌将存储在 ~/.secrets/gworkspace-mcp/token.json 中并自动刷新。

在 Claude Code 中注册

将其添加到您的 Claude Code settings.json（或 ~/.claude.json）中：

{
  "mcpServers": {
    "gworkspace": {
      "command": "gworkspace-mcp"
    }
  }
}

如果 gworkspace-mcp 不在您的 PATH 中，请使用 pip install -e . 创建的可执行文件的绝对路径（在 Windows 上，通常为 C:\Users\<you>\AppData\Local\Programs\Python\Python3XX\Scripts\gworkspace-mcp.exe）。

不安装入口点的替代调用方式：

{
  "mcpServers": {
    "gworkspace": {
      "command": "python",
      "args": ["-m", "gworkspace_mcp.server"]
    }
  }
}

OAuth 范围

服务器请求以下范围：

• spreadsheets, drive, documents, calendar

• script.projects, script.deployments, script.processes, script.metrics

• gmail.send, gmail.compose

• userinfo.email, userinfo.profile

安全说明

• 您的 client_secret.json 和 token.json 是个人的 — 切勿提交它们。仓库的 .gitignore 已经排除了它们。

• 令牌存储在 ~/.secrets/gworkspace-mcp/ 下。

• 服务器在本地运行；它不会暴露任何网络端点。

许可证

MIT — 参见 LICENSE。