Google Workspace MCP服务

谷歌工作区MCP服务器（Go）

A. 模型上下文协议 服务器在 转到1.26.2 这暴露了 Google 工作区 AI代理：Gmail、云端硬盘、日历、文档、表格、幻灯片、聊天、表单、任务、联系人、可编程搜索和应用程序脚本。实现 工具 瞄准MCP规范 2025-11-25 （通过 github.com/modelcontextprotocol/go-sdk).

目录

• 先决条件
• 快速启动
• 预构建的容器图像
• 开始（详细）
• start.sh 参考
• 包含什么
• 配置
• 认证
• 服务特定注意事项
• 故障排除
• 发展
• MCP规范合规性
• 贡献
• 许可证

先决条件

• 码头工人 （推荐） 或 转到1.26.2+ 从源代码构建
• A. 谷歌云 项目与 OAuth 2.0客户端ID （类型： 网络应用程序)以及 授权重定向URI 匹配您的服务器端口（默认 http://localhost:8000/oauth/callback)
• API已启用 在Google Cloud中为您使用的产品（Gmail、云端硬盘、日历等）

快速启动

1. OAuth客户端 — 谷歌云控制台→ 凭证：Web客户端，如上所述重定向URI，启用所需的API。

2. 跑 --从该存储库的克隆中：

   复制

   ./start.sh "YOUR_CLIENT_ID.apps.googleusercontent.com" "YOUR_CLIENT_SECRET"
   

3. 连接 --MCP网址 http://localhost:8000/mcp （必要时调整主机/端口）。复制 docs/cursor-mcp.json.example 进入 .cursor/mcp.json （或您客户的等效物）。

4. 验证 --首次使用谷歌工具会触发OAuth；在传统模式下，代理调用 start_google_auth 您在浏览器中完成同意。

对于 光标: .cursor/ 仅限于本地（未承诺）；使用 docs/cursor-mcp.json.example 作为模板 mcp.json.

预构建的容器图像

标签发布构建 连拱的 图片(linux/amd64, linux/arm64)并推动 GitHub容器注册表 通过 .github/workflows/publish.yml.

替换 OWNER/REPO 使用您的GitHub owner/repo （对于该模块的家， evert/google-workspace-mcp-go):

docker pull ghcr.io/OWNER/REPO:v1.3.0

标签通常包括 森伯 (v1.3.0), 多数人.少数人 (1.3), 主要的 (1)和a git SHA。参见 发布 对于当前版本。

这 Dockerfile 默认值 MCP_TRANSPORT=streamable-http 和 MCP_PORT=8000，它使用以下方式匹配基于HTTP的MCP客户端（Cursor、Claude Desktop） http://…/mcp.

开始（详细）

步骤1：获取Google OAuth凭据

1. 打开 谷歌云控制台→ 凭证.
2. 创建或选择一个项目。
3. API和服务→ 凭证→ 创建凭据→ OAuth客户端ID→ 网络应用程序.
4. 在...之下 授权重定向URI，添加 http://localhost:8000/oauth/callback （如果您使用，则使用具有另一个端口的同一主机 --port).
5. 复制 客户端ID 和 客户端密钥.
6. API和服务→ 图书馆 -启用您需要的每个API（Gmail、驱动器、日历…）。

步骤2：构建容器（如果使用，则可选 start.sh 单独）

git clone https://github.com/evert/google-workspace-mcp-go.git
cd google-workspace-mcp-go
docker build -t google-workspace-mcp .

镜像大小约为33 MB（无发行版，非root）。

步骤3：启动服务器

./start.sh "YOUR_CLIENT_ID.apps.googleusercontent.com" "YOUR_CLIENT_SECRET"

违约： 超文本传输协议 MCP在 http://localhost:8000/mcp, 137 MCP工具（136工作区+ start_google_auth).

步骤4：连接您的MCP客户端

光标 — .cursor/mcp.json （项目或用户配置）：

{
  "mcpServers": {
    "google-workspace": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

克劳德桌面 — claude_desktop_config.json 与相同 url 形状。

如果你使用 --port 9000，将URL设置为 http://localhost:9000/mcp 并在Google Cloud Console中添加匹配的重定向URI。

步骤5：身份验证

首次使用谷歌工具时，完成OAuth（遗留流：代理调用 start_google_auth 通过电子邮件，您可以打开URL，授予访问权限）。令牌在持久化时会自动刷新。

start.sh 参考

./start.sh <CLIENT_ID> <CLIENT_SECRET> [OPTIONS]

CLIENT_ID 和 CLIENT_SECRET 是必需的；其他一切都是可选的。

默认行为（无额外标志）

./start.sh "YOUR_CLIENT_ID.apps.googleusercontent.com" "YOUR_SECRET"

• 全部12项服务 — 137 默认情况下MCP工具(136 工作空间工具 docs/tools-inventory.md 加 **start_google_auth**OAuth 2.1省略了身份验证工具→ 136 — docs/auth-and-scopes.md)
• 港口 8000 --MCP http://localhost:8000/mcp，OAuth回调 http://localhost:8000/oauth/callback
• 内存身份验证 除非 --persistent-auth （容器重启时丢失的令牌）
• 自动重启 容器发生故障（由管理时 start.sh /Docker（如文档所示）

如果图像缺失，则在第一次运行时构建；稍后的运行会重用缓存的映像。

选项

示例

所有服务，默认端口

./start.sh "YOUR_CLIENT_ID.apps.googleusercontent.com" "GOCSPX-yourSecret"
# → 137 MCP tools on http://localhost:8000/mcp

子集：Gmail、云端硬盘、日历

./start.sh "YOUR_CLIENT_ID" "YOUR_SECRET" --services gmail,drive,calendar
# → 38 tools (15 Gmail + 16 Drive + 6 Calendar + 1 auth); OAuth scopes limited to those services

仅限Gmail+默认电子邮件

./start.sh "YOUR_CLIENT_ID" "YOUR_SECRET" --services gmail --email user@company.com
# → 16 tools (15 Gmail + 1 auth)

Gmail、日历、文档、表格

./start.sh "YOUR_CLIENT_ID" "YOUR_SECRET" --services gmail,calendar,docs,sheets

不同的端口

./start.sh "YOUR_CLIENT_ID" "YOUR_SECRET" --port 9000
# Add http://localhost:9000/oauth/callback to the OAuth client redirect URIs

持久令牌

./start.sh "YOUR_CLIENT_ID" "YOUR_SECRET" --persistent-auth

调试日志

./start.sh "YOUR_CLIENT_ID" "YOUR_SECRET" --log-level debug
# docker logs -f google-workspace-mcp

重建图像

./start.sh "YOUR_CLIENT_ID" "YOUR_SECRET" --rebuild

停止

./start.sh --stop

组合旗帜

./start.sh "YOUR_CLIENT_ID" "YOUR_SECRET" \
  --services gmail,drive,calendar \
  --port 9000 \
  --email user@company.com \
  --log-level debug

可用服务(--services)

限制 --services 减少两者 工具表面 和 OAuth作用域 同意时的请求。

包含什么

服务和工具

工具注释

每个工具都声明MCP 注释 因此客户端可以推断安全性并重试：

• 只读提示 --无写入（例如。 search_gmail_messages)
• 破坏性提示 --不可逆（例如。 delete_event)
• 概念提示 --可以安全重试（例如。 modify_event)
• OpenWorldHint --外部副作用（基本上是所有集成工具）

配置

环境变量（常见）

完整表（包括无状态模式）： docs/configuration.md.

Docker Compose

cp .env.example .env
# Edit .env with your credentials
docker compose up --build

对于持久身份验证，设置 WORKSPACE_MCP_PERSISTENT_AUTH=true 并安装 /data/credentials 如 docker-compose.yml.

认证

1. Agent calls start_google_auth with the user's email (legacy OAuth)
2. Server returns Google consent URL
3. User completes consent in the browser
4. Google redirects to http://localhost:<port>/oauth/callback
5. Server stores tokens (and refreshes them automatically)
6. Subsequent tool calls use the stored session

匹配 重定向URI 在Google Cloud控制台中 WORKSPACE_MCP_BASE_URI 和 MCP_PORT （或 start.sh --port).

坚持不懈： 没有 --persistent-auth / WORKSPACE_MCP_PERSISTENT_AUTH，代币有效 纪念 并且在重新启动时丢失。有了持久性，文件 0600，目录 0700.

静止格式： 持久化令牌是 纯JSON 在v1中；看见 docs/security.md 用于威胁模型和未来的加密/密钥环注释。

服务特定注意事项

谷歌聊天

需要 Google 工作区 （不仅仅是消费者Gmail）。聊天应用程序可能需要在 工作区管理 慰问。

可编程搜索

需要 GOOGLE_CSE_ID 从 可编程搜索引擎.

应用程序脚本

run_script_function 需要作为 API可执行文件 和 编辑 访问项目（约30次呼叫/分钟典型配额行为）。

联系人

使用 谷歌人API （不赞成使用传统的联系人API）。工具名称说 联系人 为了清楚起见。

故障排除

面向代理的错误被映射到中间件中的可操作消息中——请参阅 internal/middleware/errors.go 和 docs/architecture.md.

发展

从源代码构建

go build -o server ./cmd/server

export GOOGLE_OAUTH_CLIENT_ID="your-client-id"
export GOOGLE_OAUTH_CLIENT_SECRET="your-secret"

./server                              # stdio (default from env)
./server --transport streamable-http  # HTTP MCP

测试和棉绒

go test ./...
go test -race ./...
GOOGLE_OAUTH_CLIENT_ID=test GOOGLE_OAUTH_CLIENT_SECRET=test \
  go test -tags=integration ./internal/integration/
golangci-lint run ./...

体系结构、注册表行为和模式： docs/architecture.md, docs/code-patterns.md.

项目结构

cmd/server/main.go           Entry point, transports, wiring
internal/
  auth/                      OAuth2, scopes, callback, token persistence
  config/                    Env, flags, tier YAML
  registry/registry.go       Tool registration, tier/service/read-only filters
  services/factory.go        Google API client factory
  tools/<service>/           Per-product tools + handlers
  comments/                  Shared Drive-backed comments (Docs/Sheets/Slides)
  middleware/                Logging, Google error mapping, retry
  pkg/                       Response builder, HTML/Office helpers
configs/tool_tiers.yaml      Tier assignments

MCP规范合规性

定向 MCP 2025-11-25:

贡献

使用 docs/code-patterns.md 用于工具处理程序和输出约定。在打开PR之前，运行 golangci-lint run ./... 和 go test -race ./... （参见 .github/workflows/ci.yml).使用 .github/pull_request_template.md 当文件更改时。

许可证

请参阅 LICENSE 当您的签出包含该文件时，请将其保存在存储库根目录中。