Google Workspace MCP Server

观看实际演示：

功能介绍

Workspace MCP 可将 AI 助手连接到 Google Workspace 的全部 12 项主要服务——通过单个 MCP 服务提供 120 多种工具，支持 OAuth 2.1 多用户身份验证、三个渐进式工具层级、只读模式、完整的 CLI，以及无状态容器部署。它可通过 stdio 在本地运行，服务旧版客户端；也可通过可流式传输的 HTTP 远程运行，并完整实现最新的 MCP 规范。

本 README 仅介绍运行所需的基本内容，网站上提供了详尽文档：

安全与合规

每个页面都列出了所有工具及其层级、参数、所需权限范围和提示词示例。完整参考汇总了全部 12 项服务。

💬 Google Chat 需要一次性配置 Chat 应用并拥有 Workspace 账号——请参阅 Chat 设置常见问题。

快速开始

设置凭据 → 选择启动命令 → 连接客户端。查看包含截图的完整指南：workspacemcp.com/quick-start

你需要从 Google Cloud Console 获取 OAuth 客户端，并在一个已为你计划使用的服务启用 Google API 的项目中使用它。文档提供了每个 API 的一键启用链接，以及一条可启用所有 API 的 gcloud services enable 命令；快速入门指南会在大约五分钟内带你完成整个设置流程。

**Agentic OAuth 客户端：**此服务仅调用 Google 的 REST API，因此你的 OAuth 客户端无需启用 Google 的“将此客户端用于 AI 驱动的 Agent”设置。如果组织希望将 Agent 流量标记出来以便进行管理员控制，可以创建一个单独的客户端并启用该设置；2026 年 11 月 12 日之后，现有客户端无法更改此设置。

# 1. Credentials
export GOOGLE_OAUTH_CLIENT_ID="..."
export GOOGLE_OAUTH_CLIENT_SECRET="..."

# 2. Launch - pick a tier
uvx workspace-mcp --tool-tier core       # essential tools
uvx workspace-mcp --tool-tier extended   # core + management ops
uvx workspace-mcp --tool-tier complete   # everything

# Or cherry-pick services
uvx workspace-mcp --tools gmail drive calendar

# 1. Credentials - MCP clients connect with PKCE and no
#    secret, but Google still requires one server-side
export MCP_ENABLE_OAUTH21=true
export GOOGLE_OAUTH_CLIENT_ID="..."
export GOOGLE_OAUTH_CLIENT_SECRET="..."
#    Alternatively, point GOOGLE_CLIENT_SECRET_PATH at a client_secret.json
#    that contains the client id and secret (env vars take precedence).
export WORKSPACE_MCP_PORT=8000
export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:${WORKSPACE_MCP_PORT}/oauth2callback"
export OAUTHLIB_INSECURE_TRANSPORT=1

# 2. Launch - OAuth 2.1 requires HTTP transport
uvx workspace-mcp --transport streamable-http --tool-tier core

工具层级有助于精简上下文窗口：core 是必需工具集，extended 添加管理操作，complete 则加载所有工具。可与 --tools <service> ...、--read-only 或按服务设置的 --permissions 组合使用，也可以通过 --disabled-tools <name> ... 排除单个工具——详情请参阅服务模式文档。

连接客户端

Claude Desktop、网页和移动端 - 以 HTTP 模式运行服务，并将其添加为连接器（设置 → 连接器 → 添加自定义连接器）。这是推荐方式；连接器指南提供了分步截图说明。不支持连接器的客户端仍可使用旧版 stdio 配置——请参阅常见问题。

Claude Code

# Start the server in HTTP mode, then:
claude mcp add --transport http workspace-mcp http://localhost:8000/mcp

# Optional: install the bundled skill for better Workspace tool routing
ln -s "$(pwd)/skills/managing-google-workspace" ~/.claude/skills/managing-google-workspace

ChatGPT - 按照 ChatGPT 指南通过开发者模式连接。

VS Code、LM Studio、Open WebUI 及其他所有客户端 - 任何 MCP 客户端都可以通过可流式传输的 HTTP（推荐）或 stdio 工作。各客户端的使用指南请参阅指南和常见问题。

命令行工具

workspace-cli 可针对正在运行的服务列出并调用工具，并使用加密的磁盘 OAuth 令牌缓存——认证一次，即可永久用于脚本：

uv run workspace-cli list
uv run workspace-cli call search_gmail_messages query="is:unread" max_results=5

在此仓库中运行 uv tool install . 即可全局安装。⚠️ 请勿使用 uvx workspace-cli——一个已废弃的 PyPI 软件包占用了这个名称。

部署与高级配置

运行生产环境所需的所有内容都位于两个地方。文档介绍了认证模式和服务配置：

• OAuth 2.1 多用户身份验证 - 不记名令牌，远程或共享 HTTP 端点必需
• 无状态容器模式 - 用于受限部署，不写入磁盘
• OAuth 代理存储后端 - 分布式部署可使用内存、磁盘或 Valkey/Redis
• 外部 OAuth 提供方模式 - 使用自有身份验证服务器，仅验证不记名令牌
• 支持全域委派的服务账号 - 按请求模拟用户，可选配置域名允许列表
• 受信任网关身份 - 通过 Pomerium、Cloudflare Access、oauth2-proxy 或任何可通过 JWKS 验证的网关，实现由代理验证的逐用户隔离
• OpenTelemetry 跟踪 - 可选；除非配置 OTLP 端点，否则默认关闭
• Docker - docker build -t workspace-mcp . && docker run -p 8000:8000 workspace-mcp

高级部署指南介绍了自托管的具体事项：使用 WORKSPACE_EXTERNAL_URL 配置反向代理（包括 nginx 的 Origin: null 授权变通方案、WORKSPACE_MCP_ALLOW_NULL_ORIGIN_CONSENT 紧急绕过选项，以及 Referrer-Policy 陷阱）、源验证和 VS Code Webview 允许列表、凭据存储后端（本地目录或启用 CMEK 强制的 GCS），以及完整的环境变量参考。

生产环境调优全部通过环境变量完成；下方的名称链接至对应的参考条目。

• Google API 请求： WORKSPACE_MCP_GOOGLE_API_WORKERS、WORKSPACE_MCP_GOOGLE_API_TIMEOUT_SECONDS
• 外部 OAuth 令牌验证： WORKSPACE_MCP_TOKEN_VALIDATION_WORKERS、WORKSPACE_MCP_TOKEN_VALIDATION_CACHE_TTL
• 内存上限： WORKSPACE_MCP_MAX_FILE_BYTES、WORKSPACE_MCP_STATELESS_INLINE_MAX_BYTES、WORKSPACE_MCP_MAX_OFFICE_XML_BYTES
• 会话和健康探针： WORKSPACE_MCP_SESSION_IDLE_TIMEOUT、WORKSPACE_MCP_READINESS_TIMEOUT_SECONDS
• DNS 重绑定防护： WORKSPACE_MCP_ALLOWED_HOSTS，以逗号分隔的不含端口的主机名列表（例如 workspace-mcp,10.0.0.5）。设置后，如果请求的 Host 既不是环回地址，也不在列表中，且不是 WORKSPACE_EXTERNAL_URL 的主机或允许的来源，则会返回 403。因此，请包含客户端和健康探针使用的所有名称。未设置时，接受任何 Host。
• 无法访问调用方磁盘的托管服务： WORKSPACE_MCP_DISABLE_LOCAL_FILES 禁用本地文件后，create_drive_file、update_drive_file 和导入工具会提供 return_upload_url：调用方将字节数据 PUT 到返回的 URL。如果文件位于云端镜像文件夹（Drive for desktop）中，请先将其复制到本地目录，因为镜像路径可能会导致上传中途卡住。
• **OAuth 2.1 令牌刷新和有效期：**参见 .env.oauth21
• OAuth 2.1 同意页面：WORKSPACE_MCP_OAUTH_PROXY_REQUIRE_CONSENT=remember 会为每个 MCP 客户端在每个浏览器中仅显示一次 OAuth 代理的同意页面，而不是每次授权时都显示；跨站导航仍会提示。默认值 always 会在每次都提示。任何其他值都会导致启动失败。 对于下载，在水平扩展或缩容至零的 HTTP 部署（Cloud Run、Kubernetes）中，可以将附件暂存到 Google Cloud Storage，而不是实例本地磁盘，因为 /attachments/{id} URL 可能会指向另一台实例。安装 gcs extra，并将 WORKSPACE_MCP_FILES_GCS_BUCKET 设置为存储桶名称；对象会写入 WORKSPACE_MCP_FILES_GCS_PREFIX（默认为 attachments）下，并以有效期为一小时的 V4 签名 URL 提供，客户端会直接从 GCS 获取文件。这也使无状态模式能够返回下载 URL，而不是内嵌文件。stdio 会忽略此设置，因为其客户端会直接读取本地文件路径。运行时服务账号需要对存储桶具有对象读写权限——roles/storage.objectUser，或 roles/storage.objectCreator 加 roles/storage.objectViewer——并且如果没有导出私钥，还需要对自身拥有 roles/iam.serviceAccountTokenCreator 权限，以便通过 IAM 为 URL 签名。读取权限不可或缺：签名 URL 使用签名者的权限，因此如果没有 storage.objects.get，上传和签名都会成功，但客户端下载会失败并返回 403。服务器不会删除对象，因此请添加存储桶生命周期规则，在几小时后将其删除。

安全最佳实践

默认情况下，此服务不会向 Google API 以外的任何地方发送数据，且使用你自己的 OAuth 客户端凭据——不会进行使用情况报告、分析、许可证服务器通信，也不依赖 SaaS。采用 MIT 许可证，无 CLA、无双重许可，依赖链中也没有 copyleft。完整的安全措施——包括权限范围最小化、敏感路径拦截和无状态模式——请参阅 workspacemcp.com。

在将大模型连接到电子邮件之前，以下几点值得牢记：

• 提示词注入确实存在。 电子邮件、文档和事件中可能包含隐藏指令。只将可信数据连接到大模型，并谨慎选择启用哪些写入工具。
• 切勿将 .env、client_secret.json 或 .credentials/ 提交到源代码管理中。
• 本地文件读取受到沙盒限制，仅限于受管理的附件目录。只有在信任客户端及其数据源时，才通过 ALLOWED_FILE_DIRS 扩大范围；.env*、~/.ssh/、~/.aws/ 等类似路径始终会被拦截。
• 生产环境部署应使用 HTTPS 和 OAuth 2.1。

开发

uv sync --group dev    # install deps
uv run ruff check .    # lint
uv run pytest          # test

单文件服务模块位于 g<service>/，工具通过 @server.tool 装饰器注册，层级定义在 core/tool_tiers.yaml 中。欢迎提交 PR。

许可证

MIT——详见 LICENSE。许可证全文只有 21 行，言简意赅。

验证：