Provides tools for interacting with Google Chat, enabling reading, searching and writing across spaces, group chats, direct messages and the sidebar. Capabilities include listing and searching spaces, fetching threads and messages, searching messages and people, managing members and roles, handling reactions and pinned messages, managing read state, notification and availability settings, custom emojis, and sending, updating and deleting messages and attachments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@google-chat-mcp Search my Google Chat for messages about the Q3 launch"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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 organisation's custom emoji. Fifty-five tools cover it, every write
takes dry_run, and nothing is requested at login beyond the scopes the
tools you are actually using need.
Related MCP server: Google Workspace MCP
go install github.com/mmedum/google-chat-mcp/v2/cmd/google-chat-mcp@latestOr 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-mcpEvery archive also ships an SBOM, so you can see what is inside a binary you did not build.
Every release also carries a .mcpb bundle. Open it and Claude Desktop
installs the server and asks for your OAuth client JSON — no config file
to edit. 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.
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 and the People 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.jsonLogin 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
authorised 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.
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-hostThen 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.
Claude Code:
claude mcp add google-chat -- google-chat-mcpOr, 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 three worth
knowing now: GCM_READ_ONLY=true leaves out every tool that changes anything in Chat,
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.
Tool | What it does | Scope |
| Which account the stored credentials belong to |
|
| Spaces, group chats and direct messages you are in |
|
| One space by resource name |
|
| Named spaces by display name, including ones you are not in |
|
| The group chats holding exactly you and the people you name |
|
| The direct message with one person, created if there is none yet |
|
| Recent messages in a space, newest first, senders resolved to names |
|
| One message, with its reaction counts, what its text links to and what it quotes |
|
| Every message in one thread, oldest first |
|
| Save a message's attachment into the server's local directory |
|
| Google's search across every space you can see, or a regular-expression scan of one |
|
| Turn a name into an email address, from the directory and your contacts |
|
| Who is in a space, resolved to names and addresses |
|
| One membership: who or what it is, their role, whether they have joined |
|
| Make someone a member, manager or assistant manager |
|
| Reactions on a message |
|
| What a space has pinned |
|
| Pin a message, which everyone in the space sees |
|
| Remove a pin |
|
| How far you have read in a space |
|
| How far you have read in a thread |
|
| Clear a space's unread badge, for you only |
|
| Rewind your read mark, for you only |
|
| What changed in a space over the last 28 days | the read scope of each event type asked for |
| One of those changes by resource name |
|
| What Chat tells you about a space |
|
| Change it, or mute the space |
|
| Your own presence and custom status |
|
| Active, away, or do not disturb until a time |
|
| Set or clear the text and emoji beside your name |
|
| Your organisation's own emoji |
|
| One of them by resource name |
|
| Add one from a local image |
|
| Remove one, for everyone |
|
| Delete a space and everything in it |
|
| Your own sidebar sections |
|
| What a section holds, or which section a space sits in |
|
| Post text, exactly as given. Optionally into a thread, or carrying an uploaded file |
|
| Send a local file to a space and get the token that attaches it |
|
| Edit the text of a message you sent |
|
| Delete a message. Already gone counts as success |
|
| React to a message with a Unicode emoji |
|
| Remove a reaction, by resource name or by message, emoji and person |
|
| Start an unnamed group chat with 2 to 20 people |
|
| Create a named space with up to 20 people |
|
| Rename a space or change its description |
|
| Invite someone to a space by email |
|
| Remove a membership. Already gone counts as success |
|
| Add a sidebar section |
|
| Rename a sidebar section |
|
| Delete a sidebar section; its spaces fall back to the defaults |
|
| Reorder a section, by absolute rank or by moving it to the start or end |
|
| File a space under a section. A space already there is left alone |
|
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}
dry_run on 25 write tools. It returns the request body that
would have been sent, and the call cannot reach the network: 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.
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.
Annotations and an interaction hint. Write and delete tools ask the
client to put a person in the loop. What that is worth is the client's
decision, and the two answers are further apart than they look. In
Claude Code interactively, auto mode has run a write with no prompt at
all. Headless, the same mark refuses every write outright — an allow
rule does not suppress it, and there is nobody to ask. So if you are
automating with nobody at the keyboard, GCM_INTERACTION_HINT=false
is the way to use the write tools at all, and it is a decision to make
on purpose.
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.
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 tokenEvery 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.
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.
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.
make build # the binary
make test # race detector, coverage floor
make check # everything CI runsmake check is the definition of done: formatting, go vet,
golangci-lint, race tests with a per-package coverage floor,
govulncheck, a licence 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.
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.
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.md says how to report a vulnerability.
CODE_OF_CONDUCT.md — Contributor Covenant 3.0.
Apache 2.0 — see LICENSE.
This server cannot be deployed
Let Claude or ChatGPT search, read and send your WhatsApp messages over MCP. OAuth sign-in.
Multiple Google accounts (Gmail, Calendar, Drive, Contacts, Tasks) in one Claude connector.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
