mcp-gee-sweet

mcp-gee-sweet 为 AI 客户端提供对 Google Sheets、Docs、Drive、Calendar 和 Gmail 的深入、直接访问。它可以读取原始公式，如 =VLOOKUP()；以结构化方式构建 Docs（colspan/rowspan 表格、主题、命名样式，以及 HTML/Markdown→AST→Docs 流水线）；还支持 Drive 文件、共享和同步，以及 Calendar 事件与 Gmail 邮件、会话和草稿。

一些亮点：

• 缓存 — 重复读取时从本地缓存返回，耗时约 2ms，无需每次都往返调用 API。
• 公式访问 — 读取原始的 =VLOOKUP()、=SUM() 和 =IF() 表达式，而不只是它们生成的值。
• 本地同步 — 在本地文件夹与 Google Drive 之间进行双向同步。

安装（稳定版）：

uvx mcp-gee-sweet

安装（前沿版 — develop 上的每次代码更改）：

uvx --prerelease=allow mcp-gee-sweet

完整文档 →

---

涵盖范围

服务	工具	亮点
Google Sheets	36	公式访问、批量读写、8 种图表类型、结构操作
Google Drive	38	文件操作、共享/权限、本地同步、修订历史
Google Docs	34	完整的 HTML→Doc 流水线、表格、范围样式、主题、Markdown 导出
Google Calendar	17	事件 CRUD、跨多个日历查找空闲时段
Gmail	15	搜索和读取邮件及会话、发送和回复、可在发送前审核、编辑或丢弃的草稿、标签（仅 OAuth）。默认情况下，除非用户确认，否则不会发送任何邮件；无法询问用户的客户端会将邮件保留为草稿。参见 Gmail 发送

---

快速开始

选项 A：uv — 本地使用和开发

如果你已克隆此仓库，或只想在自己的计算机上使用该服务，只需 uv。无需 Docker。

git clone https://github.com/khuisman/mcp-gee-sweet.git
cd mcp-gee-sweet
uv sync

然后使用 stdio 传输将 MCP 客户端指向该服务（参见下文的 MCP 客户端配置）。客户端会按需将服务作为子进程启动——每个会话都有独立的进程，因此，为应用代码更改或配置更新而重启服务，不会影响其他已打开的会话。

选项 B：Docker — 持久共享服务（SSE）

如果你希望运行单个长期运行的服务，让多个客户端通过 SSE 连接（例如，让 Claude Desktop 和 Claude Code 连接到同一个实例），请使用 Docker。

git clone https://github.com/khuisman/mcp-gee-sweet.git
cd mcp-gee-sweet
echo "MCP_SERVER_TOKEN=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')" >> .env
make build   # build the container image
make start   # start the server (SSE on port 47000)
make logs    # tail logs

将 MCP 客户端指向 http://localhost:47000/sse，并在 Authorization: Bearer <token> 标头中发送 .env 中的令牌（参见下方的 SSE 配置）。服务会拒绝任何不含该令牌的请求。不使用 Docker 时，--transport sse 和 --transport streamable-http 仅监听 127.0.0.1；若要在其他地址提供服务，则需要设置 MCP_SERVER_TOKEN；参见 HTTP 传输身份验证。

注意： 使用 SSE 时，所有客户端共用一个服务进程。代码更改或重启（make restart）后，你还必须重启每个 MCP 客户端，才能重新连接。

---

配置

默认情况下，服务会按顺序尝试各种身份验证方式，首先是 OAuth——它会以你的身份进行身份验证，并拥有完整的个人 Drive 访问权限，适用于本地/开发环境（上文的选项 A）。要使用 OAuth，请从 GCP Console 下载 OAuth Client ID JSON，并将服务指向该文件：

export CREDENTIALS_PATH="/path/to/credentials.json"
export TOKEN_PATH="/path/to/token.json"
mcp-gee-sweet auth   # one-time browser login; `uvx mcp-gee-sweet auth` for a PyPI install

在 MCP 客户端的 env 中传入相同的 CREDENTIALS_PATH 和 TOKEN_PATH。没有令牌的 stdio 服务不会自行打开浏览器。相反，它会在首次工具调用时提供 Google 授权链接（或者你可以运行 mcp-gee-sweet auth），然后重试该调用。会话中途令牌被撤销时也会以相同方式处理，无需重启。

此外，还支持服务账号（推荐用于无头服务部署，见上文的选项 B）、以 base64 注入凭据，以及应用默认凭据。Gmail 工具需要 OAuth。所有选项请参阅身份验证。

---

MCP 客户端配置

Claude Desktop — 一键安装包： 从最新的 GitHub Release 下载 mcp-gee-sweet-<version>.mcpb，并在 Claude Desktop 中打开。它会要求你提供 OAuth 客户端文件，无需编辑配置（详情）。

Claude Desktop — stdio（克隆的仓库）：

{
  "mcpServers": {
    "mcp-gee-sweet": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-gee-sweet", "mcp-gee-sweet"],
      "env": {
        "CREDENTIALS_PATH": "/path/to/credentials.json",
        "TOKEN_PATH": "/path/to/token.json"
      }
    }
  }
}

Claude Desktop — SSE（Docker）：

{
  "mcpServers": {
    "mcp-gee-sweet": {
      "transport": "sse",
      "url": "http://localhost:47000/sse",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

更多选项（包括工具筛选），请参阅客户端设置。

在工具数量受限的客户端中使用

有些 MCP 客户端会限制接受的工具数量，而该服务注册所有工具后会超过每个客户端的上限：

客户端	上限
VS Code + GitHub Copilot（Agent 模式）	每个请求 128 个工具，包含内置工具。超出后，每个请求都会失败，并提示 "Cannot have more than 128 tools per request"
Windsurf	所有服务合计 100 个工具
Cursor	取决于模型（"Too many MCP tools are enabled for this mode"）
Google Antigravity	每个服务 100 个工具（用户反馈）

在这些客户端中，请在服务的 env 中将 ENABLED_TOOLS 设为建议的子集之一，每个子集少于 100 个工具，例如，所有 Docs 工具，或 Docs + Drive 的组合。工具数量受限的客户端提供了可直接粘贴到 VS Code、Cursor 和 Windsurf 的配置。

---

文档

• 工具 — 完整的工具参考，按领域分组
• 身份验证 — 全部四种身份验证方式
• 配置 — 环境变量、缓存、工具筛选
• 客户端设置 — MCP 客户端配置示例
• 设计原则 — 工具纳入策略、复合工具决策
• 路线图 — 计划中的功能和已知缺口

---

贡献

有关设置、QA 工作流和 PR 指南，请参阅 CONTRIBUTING.md。任何稳定版 PyPI 发布前，都必须有经签署确认的 docs/qa/runs/vX.Y.Z.md 记录 — QA 工作流请参阅 docs/qa/README.md。

许可证

MIT — 请参阅 LICENSE。

致谢

• xing5/mcp-google-sheets — 本项目分叉自此上游项目
• FastMCP
• freema/mcp-gsheets 和 piotr-agier/google-drive-mcp — 路线图灵感来源