google-chat-mcp

google-chat-mcp

将 Google Chat 用作 MCP 工具。读取、搜索并向你的空间、私信和侧边栏写入内容。

这是一个通过 stdio 使用 MCP 的 Go 单一二进制文件。它作为客户端的子进程，在你自己的设备上运行，并使用你自己的 Google 账号。无需托管服务、无需共享部署，也无需服务账号：创建一个 Google OAuth 客户端，登录一次，刷新令牌就会保存在你的 OS 密钥环中。Claude Code、Claude Desktop 和任何其他 MCP 客户端都可以使用它。

为什么选择 google-chat-mcp

聊天集成通常是应用：它们以机器人身份发帖，只能查看有人邀请它们加入的空间，而且需要由管理员配置服务账号。这个工具以你的身份运行。它可以访问你账号本来就能访问的内容，你发送的消息也来自你本人，而不是一个使用你名字的应用。

它还让你能够访问 Chat 中仅限用户身份的部分，而应用身份完全无法访问这些内容：侧边栏分区、你在空间或话题中的已读进度、你的在线状态和自定义状态，以及组织的自定义表情符号。58 个工具涵盖这些功能，大多数写入操作都支持 dry_run，登录时除了实际使用的工具所需的权限范围外，不会请求其他权限。

安装

go install github.com/mmedum/google-chat-mcp/v8/cmd/google-chat-mcp@latest

或者从最新版本下载已签名的压缩包——适用于 amd64 和 arm64 架构上的 Linux、macOS 和 Windows——并在运行前进行验证：

sha256sum -c checksums.txt --ignore-missing

# The checksum file is signed with a keyless Sigstore certificate tied to
# the release workflow's identity. The bundle carries both.
cosign verify-blob checksums.txt \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp 'https://github\.com/mmedum/google-chat-mcp/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# And the archive itself carries build provenance.
gh attestation verify google-chat-mcp_*.tar.gz --repo mmedum/google-chat-mcp

每个压缩包还附带 SBOM，让你了解自己未构建的二进制文件包含哪些内容。

Claude Desktop

每个版本还附带一个 .mcpb 捆绑包。打开它，Claude Desktop 就会安装服务，并询问配置文件中需要的设置，无需编辑文件：你的 OAuth 客户端 JSON（可以留空以使用上次 login 记录的客户端）、配置文件、只读模式、工具集和附件文件夹。无法撤销的工具（enable_destructive）默认保持关闭，附件传输也会保持关闭，直到你选择文件夹。此服务不会在调用前征求许可。Claude Desktop 会逐个审批工具；始终允许的工具之后会直接运行，因此除非需要使用相关工具，否则请保持 enable_destructive 关闭。

该捆绑包涵盖 macOS、Windows 和 Linux 的两种架构：macOS 使用通用二进制文件，Windows 使用 amd64，Linux 使用一个小型启动器，在启动时选择正确的二进制文件，因为捆绑包清单没有用于指定架构的字段。它的 SHA-256 值列在同一份已签名的 checksums.txt 中。此版本已在 MCP 注册表中登记，名称为 io.github.mmedum/google-chat-mcp。

此捆绑包不会为你登录。请先安装二进制文件并运行一次 google-chat-mcp login，捆绑包就会使用相同的凭据。Claude Code 不会安装 .mcpb 文件，因此请使用下面的命令。

设置 Google

你需要拥有自己的 OAuth 客户端。首次设置大约需要十五分钟，docs/gcp-setup.md 中有详细步骤。简而言之：创建一个项目，启用 Google Chat API、People API 和 Cloud Identity API，使用此服务请求的范围配置同意屏幕，然后创建一个类型为 Desktop app 的 OAuth 2.0 Client ID。下载 JSON 文件。

然后登录：

google-chat-mcp login --client-secret ./client_secret.json

登录时会打开浏览器；如果没有可用的浏览器，则会打印 URL（--no-browser 可强制采用这种方式）。回调会通过 PKCE 和 state，在随机端口上到达 127.0.0.1。刷新令牌会存入操作系统密钥环；如果没有密钥环，则会存入权限为 0600 的文件，并由命令告知你这一点。在 Windows 上，Go 文件模式只能设置只读属性，因此保护该文件的是其目录继承的 ACL，而不是文件模式。

google-chat-mcp status 会显示已登录的账户以及令牌的存放位置。google-chat-mcp logout 会在 Google 处撤销令牌并删除本地副本。

google-chat-mcp status --json 会在标准输出中以一个 JSON 对象打印相同的状态，供需要在启动此服务前确认其是否已获授权的脚本使用。credentials.resolved 是用于分支判断的字段，credentials.signed_in 可区分“尚无配置文件”和“有配置文件但没有令牌”，只有在字段被移除或含义发生变化时，schema_version 才会变化；账户会按文本输出中的相同方式，精确保留域名并屏蔽其他部分。人类可读输出中的标签可以在任何版本中改写，对象则不会。

通过 SSH 登录

回调会发往远程主机的环回地址，而你的浏览器在本地，因此需要转发端口。端口是随机选取的，只有在登录等待时才会打印，因此请从打印的 URL 中读取端口——它会以百分号编码的形式显示为 127.0.0.1%3A<port>。然后在第二个本地终端中运行：

ssh -N -L <port>:127.0.0.1:<port> user@remote-host

接着在本地打开该 URL。如果 ssh 报告 bind: Address already in use，请按 Ctrl-C 取消登录，然后重新运行以获取另一个端口。

连接客户端

Claude Code：

claude mcp add google-chat -- google-chat-mcp

或者，在客户端配置文件中：

{
  "mcpServers": {
    "google-chat": {
      "command": "google-chat-mcp"
    }
  }
}

Claude Desktop 会从自己的配置文件中读取相同格式的配置。如果二进制文件不在应用的 PATH 中，请在配置中使用其绝对路径；或者安装上方的 .mcpb 捆绑包，无需编辑任何内容。

每项设置都是一个环境变量，详见 docs/configuration.md。现在值得了解的四项设置：GCM_READ_ONLY=true 会排除所有会修改 Chat 内容的工具；GCM_ENABLE_DESTRUCTIVE=true 会添加不可撤销的工具；GCM_PROFILE 可让一台机器同时保存工作账户和个人账户；GCM_LOCAL_DIR 用于指定唯一一个允许读写文件的目录。如果不设置最后一项，服务完全不会访问文件，三个用于移动文件的工具也会说明这一点。

工具

工具	功能	范围
whoami	已存储的凭据属于哪个账号	openid email profile
list_spaces	你加入的空间、群聊和私信	chat.spaces.readonly
get_space	根据资源名称获取一个空间	chat.spaces.readonly
search_spaces	根据显示名称查找你加入的已命名空间；使用 use_admin_access 时可查找所有空间	chat.spaces.readonly；使用 use_admin_access 时需要 chat.admin.spaces.readonly
find_group_chats	查找仅包含你和指定人员的群聊	chat.memberships.readonly、chat.spaces.readonly
find_direct_message	查找与某人的私信；如果尚不存在，则创建一个	chat.spaces.readonly、chat.spaces.create
get_messages	获取空间中的近期消息，按时间从新到旧排列，并将发送者解析为姓名	chat.messages.readonly
get_message	获取一条消息，包括其表情回应数量、文本链接的目标以及引用的内容	chat.messages.readonly
get_thread	获取某个会话串中的所有消息，按时间从旧到新排列	chat.messages.readonly
download_attachment	将消息附件保存到服务的本地目录	chat.messages.readonly
search_messages	使用 Google 的搜索功能搜索你可查看的所有空间，或对单个空间进行正则表达式扫描	chat.messages.readonly；使用 unread_only 时需要 chat.users.readstate.readonly；使用 space_type 和 space_name 时需要 chat.spaces.readonly
search_people	从目录和联系人中将姓名转换为电子邮件地址	directory.readonly、contacts.readonly
find_group	将 Google 群组的电子邮件地址转换为 add_member 所需的 ID	cloud-identity.groups.readonly
list_members	查看空间中的成员；将人员和群组解析为姓名和地址；也可按需查看各群组中的成员	chat.memberships.readonly、directory.readonly、cloud-identity.groups.readonly
get_member	获取一条成员资格信息：成员是谁或是什么、其角色，以及是否已加入	chat.memberships.readonly、directory.readonly、cloud-identity.groups.readonly
update_member_role	将管理员恢复为普通成员	chat.memberships
promote_member	将某人设为管理员或助理管理员；需要 GCM_ENABLE_DESTRUCTIVE	chat.memberships
list_reactions	查看消息的表情回应	chat.messages.readonly
list_pinned_messages	查看空间中置顶的内容	chat.spaces.pins.readonly
pin_message	置顶一条消息，空间中的所有人都能看到	chat.spaces.pins
unpin_message	取消置顶	chat.spaces.pins
get_space_read_state	查看你在空间中的阅读进度	chat.users.readstate.readonly
get_thread_read_state	查看你在会话串中的阅读进度	chat.users.readstate.readonly
mark_space_read	仅为你清除空间的未读徽标	chat.users.readstate
mark_space_unread	仅为你将阅读标记回退	chat.users.readstate
list_space_events	查看空间在过去 28 天内的变更	所请求的每种事件类型对应的读取范围
get_space_event	根据资源名称获取一项变更	chat.spaces.readonly
get_space_notification_setting	查看 Chat 如何通知你有关空间的消息；不受 GCM_READ_ONLY 限制	chat.users.spacesettings
update_space_notification_setting	更改通知设置，或将空间静音	chat.users.spacesettings
get_availability	查看你自己的在线状态和自定义状态	chat.users.availability.readonly
set_availability	将状态设为在线、离开或请勿打扰，直至指定时间	chat.users.availability
set_custom_status	设置或清除姓名旁边的文字和表情符号	chat.users.availability
list_custom_emojis	查看你所在组织的自定义表情符号	chat.customemojis.readonly
get_custom_emoji	根据资源名称获取其中一个自定义表情符号	chat.customemojis.readonly
create_custom_emoji	从本地图像添加自定义表情符号	chat.customemojis
delete_custom_emoji	为所有人删除一个自定义表情符号；需要 GCM_ENABLE_DESTRUCTIVE	chat.customemojis
delete_space	删除一个空间及其中的所有内容；需要 GCM_ENABLE_DESTRUCTIVE	chat.delete
list_sections	查看你自己的侧边栏分区	chat.users.sections.readonly
list_section_items	查看分区中的内容，或某个空间所属的分区	chat.users.sections.readonly
send_message	在 Chat 中按其语法或 Markdown 原样发送文本。也可选择发送到会话串、引用消息或附带已上传的文件	chat.messages.create；引用消息时需要 chat.messages.readonly
upload_attachment	将本地文件发送到空间，并获取用于附加该文件的令牌	chat.messages.create
update_message	编辑你发送的消息文本	chat.messages
delete_message	删除一条消息；需要 GCM_ENABLE_DESTRUCTIVE。消息已删除时也视为成功	chat.messages
delete_thread	删除会话串的首条消息及其所有回复；需要 GCM_ENABLE_DESTRUCTIVE	chat.messages
add_reaction	使用 Unicode 表情符号回应一条消息	chat.messages.reactions
remove_reaction	根据资源名称，或根据消息、表情符号和人员移除表情回应	chat.messages.reactions
create_group_chat	与 2 至 20 人发起一个未命名群聊	chat.spaces.create
create_space	创建一个最多包含 20 人的私人命名空间	chat.spaces.create
update_space	重命名空间、更改其说明，或将其设为私人空间	chat.spaces
set_space_audience	向目标受众开放空间；需要 GCM_ENABLE_DESTRUCTIVE	chat.spaces
add_member	通过电子邮件邀请组织内的人员加入空间，或将 Google 群组添加到不允许组织外人员加入的空间	chat.memberships；检查地址时需要 chat.spaces.readonly、directory.readonly
add_external_member	邀请组织外的人员，或将 Google 群组添加到允许外部人员加入的空间；需要 GCM_ENABLE_DESTRUCTIVE	chat.memberships；检查群组地址时需要 cloud-identity.groups.readonly
remove_member	移除成员资格；需要 GCM_ENABLE_DESTRUCTIVE。成员已移除时也视为成功	chat.memberships
create_section	添加侧边栏分区	chat.users.sections
rename_section	重命名侧边栏分区	chat.users.sections
delete_section	删除侧边栏分区；需要 GCM_ENABLE_DESTRUCTIVE；其中的空间将移回默认位置	chat.users.sections
position_section	调整分区顺序，可按绝对排名排列，或将其移到开头或末尾	chat.users.sections
move_space_to_section	将空间归入某个分区。如果空间已在该分区中，则不作更改	chat.users.sections
“版块”就是你自己的侧边栏。其中的内容不会改变任何空间，也不会被其他人看到。

三个资源包含与对应工具相同的内容，供会将资源纳入上下文的客户端使用：

• gchat://spaces/{space_id}
• gchat://spaces/{space_id}/messages/{message_id}
• gchat://spaces/{space_id}/threads/{thread_id}

安全性

• 29 个写入工具支持 dry_run。 它会返回原本要发送的请求正文，并且调用无法写入：该标志会将请求放到 HTTP 客户端拒绝写入的上下文中，因此如果工具忘了自己的预览分支，就会明确报错，而不是发布内容。预览仍可能读取它展示或检查的内容，例如引用消息所指的消息，或删除操作会重复显示的文本。

• GCM_READ_ONLY=true 时，写入工具不会注册。 未注册的工具无法调用，不受客户端权限模式或模型请求的影响。它在启动服务时设置，因此对整个会话生效，而非只对单次调用生效。运行时若设置了该变量，执行 google-chat-mcp login 会请求只读权限范围，因此该令牌也无法写入。之前登录获得的令牌会保留其写入权限范围，直到你再次登录；重新启用写入也需要再次登录。

• 除非你明确启用，否则不可撤销的操作不会注册。 删除操作、delete_thread、set_space_audience、promote_member 和 add_external_member 只有在设置了 GCM_ENABLE_DESTRUCTIVE=true 时才会启用。此时每次调用都必须包含 confirm: true。delete_message、delete_thread、delete_space、delete_custom_emoji 和 set_space_audience 还会重复说明操作对象：消息的开头内容，或空间或表情符号的名称。服务会先读取目标对象；如果不匹配，就会以 [stale] 拒绝调用。因此客户端展示的调用会明确说明将删除哪条消息或哪个空间。

• 每次调用由你的客户端审批；服务不会向你询问。 Claude Code 会询问你在设置中 permissions.ask 下列出的工具。claude.ai 和 Codex 会提示你确认标记了 destructiveHint 的工具；上面列表中所有需要设置 GCM_ENABLE_DESTRUCTIVE 的工具都带有此标记。VS Code 会提示你确认每个会产生更改的工具，包括 download_attachment。在 Claude Code 中，将发布、邀请、共享或删除内容的写入工具添加到设置的 permissions.ask 下，并用你为服务指定的名称替换 google-chat：

  {
    "permissions": {
      "ask": [
        "mcp__google-chat__send_message", "mcp__google-chat__update_message",
        "mcp__google-chat__upload_attachment",
        "mcp__google-chat__create_space", "mcp__google-chat__create_group_chat",
        "mcp__google-chat__find_direct_message",
        "mcp__google-chat__add_member", "mcp__google-chat__add_external_member",
        "mcp__google-chat__update_member_role", "mcp__google-chat__promote_member",
        "mcp__google-chat__remove_member", "mcp__google-chat__update_space",
        "mcp__google-chat__pin_message", "mcp__google-chat__create_custom_emoji",
        "mcp__google-chat__delete_message", "mcp__google-chat__delete_thread",
        "mcp__google-chat__delete_section"
      ]
    }
  }
  

  delete_space、set_space_audience 和 delete_custom_emoji 无需配置规则：它们带有 Claude Code 的 requiresUserInteraction 标记，因此 Claude Code 2.1.199 或更高版本会在每种交互模式下对每次调用进行询问；在无法询问用户的环境中则会拒绝调用。

• 默认情况下，内容不会触达整个空间或超出空间范围。 发布或编辑内容时若提及所有人，即 <users/all>，操作会被拒绝。创建的空间默认为私密，update_space 不会将空间设为公开。在允许组织外人员加入的空间中，add_member 会拒绝添加组织目录中不存在的地址和任何 Google Group；update_member_role 也不会将任何人设为管理员。这些操作分别由 add_external_member 和 promote_member 执行。

• send_message 会原样发布正文。 不添加前缀、后缀或“由助手发送”之类的页脚。

• 重试发布不会造成重复。 每条消息都带有客户端选择的 ID，因此超时后重试会返回已发布的内容，而不会再次发布。

• 日志不会记录负载。 日志会记录调用了哪个工具、目标资源以及调用结果。消息文本、地址、名称和搜索词不会写入日志；如果其中任何内容出现在日志中，测试就会导致构建失败。

工作原理

MCP client ──stdio──► google-chat-mcp
                       ├── tools      one handler per tool; shapes the reply
                       ├── service    the rules: idempotency, degrading, search
                       ├── gchat      REST client for Chat, People and OIDC
                       ├── directory  email cache, so a page of messages costs one lookup
                       └── auth       refresh token → access token

每个空间、消息和线程都通过资源名称寻址，而非通过位置寻址；只要 Google 返回令牌，列表操作就会持续翻页，包括跳过空页的情况。Chat 在应用页面大小限制后再应用筛选条件时，会返回空页。

获取帮助

如果某些功能无法正常工作，请运行 google-chat-mcp doctor。它会检查凭据、已授予的范围以及 Google 的实际响应，并指出缺少什么 — 首次运行时的大多数问题，都是因为 API 从未启用，或同意屏幕中没有添加你。

如果这仍无法解释问题， 请提交 issue。切勿在 issue 中粘贴空间或消息资源名称、消息文本、client_secret.json 或令牌；请改为描述其形态。安全问题请通过 SECURITY.md 私下报告。

版本管理

工具名称及其输出字段在同一主版本内保持稳定。任何需要你采取行动的变更 — 新增范围、重新登录，或更改客户端配置中的命令 — 都会在 CHANGELOG.md 中标记为 Breaking:，每个版本的发布说明也由此生成。

开发

make build     # the binary
make test      # race detector, coverage floor
make check     # everything CI runs

make check 是完成标准：格式检查、go vet、golangci-lint、带有逐包覆盖率下限的竞态测试、govulncheck、许可证检查、stdio 冒烟测试、与已发布工具接口的架构差异检查、API 覆盖率门禁（若某个 Google API 方法没有判定，或本服务发出的调用没有对应条目，则检查失败），以及过期检查门禁（若 README、文档或变更日志与代码不同步，则检查失败）。

文档

• docs/architecture.md — 请求流程、包布局、约定背后的证据日志，以及贡献者不应撤销的设计决策。
• docs/configuration.md — 每个环境变量。
• docs/gcp-setup.md — Google Cloud 项目和 OAuth 客户端的逐步设置说明。
• docs/security.md — 威胁模型。
• docs/runbook.md — 轮换或恢复凭据。

贡献

问题和缺陷请提交到 issues；欢迎提交拉取请求。 CONTRIBUTING.md 介绍了分支和审查流程，且必须通过 make check。

安全

SECURITY.md 说明了如何报告漏洞。

行为准则

CODE_OF_CONDUCT.md — Contributor Covenant 3.0。

许可证

Apache 2.0 — 详见 LICENSE。