google-chat-mcp

Google Chat as MCP tools. Read, search and write to your spaces, DMs and sidebar.

A single Go binary that speaks MCP over stdio. It runs as a subprocess of your client, on your own machine, against your own Google account. There is no server to host, no shared deployment and no service account: you create a Google OAuth client, log in once, and the refresh token stays in your OS keyring. Claude Code, Claude Desktop and any other MCP client can drive it.

Why google-chat-mcp

Chat integrations are normally apps: they post as a bot, see only the spaces somebody added them to, and need a service account an administrator provisions. This one runs as you. It reaches what your account already reaches, and messages you send are from you, not from an app with your name on it.

That also puts the user-scoped half of Chat in reach, which an app identity cannot get to at all: your sidebar sections, how far you have read in a space or a thread, your availability and custom status, and your organization's custom emoji. Fifty-eight tools cover it, most writes take dry_run, and nothing is requested at login beyond the scopes the tools you are actually using need.

Install

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

Or take a signed archive from the latest release — Linux, macOS and Windows, on amd64 and arm64 — and verify it before you run it:

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

Every archive also ships an SBOM, so you can see what is inside a binary you did not build.

Claude Desktop

Every release also carries a .mcpb bundle. Open it and Claude Desktop installs the server and asks for the settings a config file would carry, with no file to edit: your OAuth client JSON, which may be left empty to use the one login recorded, the profile, read-only, the toolsets and the attachment folder. The tools that cannot be taken back (enable_destructive) stay off unless you turn them on, and so does attachment transfer until you pick a folder. This server asks nobody before a call. Claude Desktop approves each tool, and a tool you always allow then runs unasked, so leave enable_destructive off unless you need its tools.

It covers macOS, Windows and Linux on both architectures each: macOS through a universal binary, Windows through amd64, and Linux through a small launcher that picks the right binary at start, because a bundle manifest has no key for the architecture. Its SHA-256 is in the same signed checksums.txt. The release is listed in the MCP registry as io.github.mmedum/google-chat-mcp.

The bundle does not log you in. Install the binary as well, run google-chat-mcp login once, and the bundle picks up the same credentials. Claude Code does not install .mcpb files, so it uses the command below.

Set up Google

You need your own OAuth client. It takes about fifteen minutes once, and docs/gcp-setup.md walks through it. In short: create a project, enable the Google Chat API, the People API and the Cloud Identity API, configure the consent screen with the scopes this server asks for, and create an OAuth 2.0 Client ID of type Desktop app. Download the JSON.

Then log in:

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

Login opens your browser, or prints the URL when there is no browser to open (--no-browser forces that). The callback lands on 127.0.0.1 on a random port, with PKCE and state throughout. The refresh token goes into your OS keyring; if there is no keyring, it goes into a 0600 file and the command tells you so. On Windows a Go file mode only sets the read-only attribute, so what protects that file there is the ACL its directory inherits, not the mode.

google-chat-mcp status says which account is signed in and where the token lives. google-chat-mcp logout revokes the token at Google and deletes the local copy.

google-chat-mcp status --json prints the same state as one JSON object on stdout, for a script that needs to know whether this server is authorized before starting it. credentials.resolved is the field to branch on, credentials.signed_in distinguishes "no profile yet" from "profile but no token", schema_version changes only when a field is removed or its meaning changes, and the account is masked to its domain exactly as the text output masks it. A label in the human output is free to be reworded in any release; the object is not.

Logging in over SSH

The callback goes to the remote host's loopback address, and your browser is local, so forward the port. It is chosen at random and printed only once login is already waiting, so read it out of the printed URL — it appears percent-encoded, as 127.0.0.1%3A<port> — and in a second local terminal:

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

Then open the URL locally. If ssh reports bind: Address already in use, cancel the login with Ctrl-C and run it again to draw another port.

Connect a client

Claude Code:

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

Or, in a client config file:

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

Claude Desktop reads the same shape from its own config file. Use the binary's absolute path there if it is not on the app's PATH, or install the .mcpb bundle above and edit nothing.

Every setting is an environment variable, listed in docs/configuration.md. The four worth knowing now: GCM_READ_ONLY=true leaves out every tool that changes anything in Chat, GCM_ENABLE_DESTRUCTIVE=true adds the tools that cannot be taken back, GCM_PROFILE lets one machine hold a work account and a personal one, and GCM_LOCAL_DIR names the one directory files may be written to and read from. Without that last one the server touches no files at all, and the three tools that move them say so.

Tools

Sections are your own sidebar. Nothing there changes a space, and nobody else sees it.

Three resources carry the same content as the matching tools, for a client that includes resources in its context:

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

Safety

• `dry_run` on 29 write tools. It returns the request body that

would have been sent, and the call cannot write: the flag puts the request on a context the HTTP client refuses to write under, so a tool that forgot its own preview branch fails loudly instead of posting. A preview may still read what it shows or checks, such as the quoted message a quote names or the text a delete repeats.

• `GCM_READ_ONLY=true` leaves the write tools unregistered. A tool

that is not registered cannot be called, whatever permission mode the client is in or whatever a model asks for. It is set where you start the server, so it binds the whole session rather than one call. A google-chat-mcp login run with it set asks for read-only scopes, so that token cannot write either. A token from an earlier login keeps its write scopes until you log in again, and turning writes back on takes another login.

• What cannot be taken back is not registered unless you say so.

The deletes, delete_thread, set_space_audience, promote_member and add_external_member exist only with GCM_ENABLE_DESTRUCTIVE=true. Each call then says confirm: true. delete_message, delete_thread, delete_space, delete_custom_emoji and set_space_audience also repeat what they act on: how the message begins, or the space's or the emoji's name. The server reads the target first and refuses [stale] when it differs, so the call your client shows you says which message or space goes.

• Your client approves each call; the server asks you nothing.

Claude Code asks for the tools you list under permissions.ask. claude.ai and Codex prompt for a tool marked destructiveHint, which every tool in the list above that needs GCM_ENABLE_DESTRUCTIVE carries. VS Code prompts for every tool that changes anything, download_attachment included. In Claude Code, put the writes that post, invite, share or delete under permissions.ask in your settings, with the name you gave the server in place of 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 and delete_custom_emoji need no rule: they carry Claude Code's requiresUserInteraction mark, so Claude Code 2.1.199 or later asks on every call in every interactive mode, and refuses them where nobody can be asked.

• Nothing reaches the whole space or past it by default. A post or

an edit that mentions everyone, <users/all>, is refused. A space is created private, and update_space does not open one. In a space that admits people from outside your organization, add_member refuses an address your organization's directory does not know and every Google Group, and update_member_role makes nobody a manager: those are add_external_member and promote_member.

• `send_message` posts the body verbatim. No prefix, no suffix, no

"sent by an assistant" footer.

• A retried post cannot land twice. Each message carries a

client-chosen id, so a retry after a timeout returns what already landed instead of posting again.

• Logs never carry the payload. They record which call was made, to

which resource, and how it ended. Message text, addresses, names and search terms stay out, and a test fails the build if one appears.

How it works

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

Every space, message and thread is addressed by its resource name, never by position, and a listing keeps paging while Google returns a token — including past an empty page, which Chat returns when it applies the page size before the filter.

Getting help

If something does not work, run google-chat-mcp doctor. It checks the credentials, the granted scopes and what Google actually answers, and names what is missing — most first-run trouble is an API that was never enabled or a consent screen without you on it.

If that does not explain it, open an issue. Never paste a space or message resource name, message text, a client_secret.json or a token into one; describe the shape instead. Security problems go through SECURITY.md, privately.

Versioning

Tool names and their output fields are stable within a major version. A change needing you to act — a new scope, another login, a different command in your client config — is marked Breaking: in CHANGELOG.md, which is also what each release's notes are made from.

Development

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

make check is the definition of done: formatting, go vet, golangci-lint, race tests with a per-package coverage floor, govulncheck, a license check, a stdio smoke test, a schema diff against the released tool surface, an API-coverage gate that fails when a Google API method has no verdict on it or a call this server makes has no row, and a staleness gate that fails when this README, the docs or the changelog drift from the code.

Documentation

• docs/architecture.md — the request flow, the

package layout, the evidence log behind the conventions, and the design decisions a contributor should not undo.

• docs/configuration.md — every environment

variable.

• docs/gcp-setup.md — the Google Cloud project and

OAuth client, step by step.

• docs/security.md — the threat model.
• docs/runbook.md — rotating or recovering

credentials.

Contributing

Questions and bugs go in issues; pull requests are welcome. CONTRIBUTING.md covers the branch and review flow, and make check is what has to pass.

Security

SECURITY.md says how to report a vulnerability.

Code of conduct

CODE_OF_CONDUCT.md — Contributor Covenant 3.0.

License

Apache 2.0 — see LICENSE.