Google Chat MCP

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.

It is for one person who uses Google Chat, on a Workspace or a personal Google account, and wants an assistant to read and write Chat as them. You create your own OAuth client in Google Cloud once; on Workspace, your administrator has to allow user-managed OAuth clients. A Workspace administrator can also turn on a toolset that manages every named space in the organization.

Goals and non-goals

Goals:

• Act as you. Every call runs as the signed-in account, with its access and nothing more.
• One binary per person. It runs on your machine, as a subprocess of your client, with your own OAuth client and token. Nothing is hosted or shared.
• Safe by default. What cannot be taken back is registered only when you turn it on, read-only mode removes every write, and most writes can be previewed with dry_run.
• Nothing added, nothing logged. send_message posts the body verbatim, and the logs never carry message text, addresses or search terms.
• Keep working when Google changes. An unknown field in a response is logged by name, never fatal.

Non-goals:

• A Chat app or bot. There is no service account, no app authentication and no domain-wide delegation, so it never posts as an app or acts for another user.
• A hosted service. It speaks stdio only, so Claude on the web and on mobile cannot reach it.
• Reading other people's messages as an administrator. The admin toolset manages spaces and memberships. Google offers no administrator access to messages.
• Filtering what a message says. Message text reaches your client verbatim, and this server cannot tell an instruction in it from a sentence.
• Asking you before a call. Your client approves each call; the server asks nothing.

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. Login asks for the administrator scopes only when you turn the admin toolset on, and only for read-only scopes under GCM_READ_ONLY.

Install

go install github.com/mmedum/google-chat-mcp/v9/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, list the scopes this server asks for if the app is External, 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 — 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. These are worth knowing first: 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 tools that move files say so.

Tools

| `get_space_no