google-chat-mcp

A production-grade MCP server that exposes Google Chat to any MCP-compatible client. Read, search, and reply to spaces and DMs through natural-language prompts in your MCP client of choice.

Two transports ship in this repo:

• Stdio (recommended for individual users) — install from PyPI with

uv tool install google-chat-mcp, run a one-time OAuth login against your own Google account, then launch the server as a subprocess under Claude Code, opencode, Cursor, etc.

• Streamable HTTP (shared / hosted deployments) — self-host in Docker

for teams; the MCP client connects over HTTPS and walks the OAuth flow per-user against the operator's Google app.

Per-user OAuth against Google Workspace or consumer Google accounts. No service accounts, no domain-wide delegation, no publishing step.

Which mode do I want?

Pick one path and jump straight to its setup.

Tool surface

Three MCP Resources are dual-exposed for host-UI inclusion:

• gchat://spaces/{space_id} — same shape as get_space
• gchat://spaces/{space_id}/messages/{message_id} — same shape as get_message
• gchat://spaces/{space_id}/threads/{thread_id} — same shape as get_thread

Dry-run on send_message

Set dry_run: true on any send_message call to preview the exact JSON body the server would post. The tool returns rendered_payload and does NOT hit the Chat API. Intended for ungated Agent-SDK loops and MCP clients running with bypassPermissions — preview, inspect, then re-invoke without dry_run to actually post. Rate-limit and audit still fire on the dry run.

Granular-consent errors

Google's January 2026 granular-consent rollout lets users toggle individual scopes at grant time. When a tool call fails because a scope is missing, the server returns a structured ToolError naming the exact scope:

Missing required OAuth scope: https://www.googleapis.com/auth/chat.messages.reactions.
Re-run `google-chat-mcp login` (stdio) or re-consent in your MCP client (HTTPS).

Stdio mode — individual users

1. One-time GCP setup (~15 minutes)

See docs/gcp-setup.md for the full walkthrough. Summary:

1. Create a Google Cloud project.
2. Enable the Google Chat API, People API, and Google OIDC / userinfo.
3. Configure the OAuth consent screen (upload your own app name, logo, contact email).
4. Add the v2 scopes listed above.
5. Add yourself as a test user if the consent screen is in "Testing" state.
6. Create an OAuth 2.0 Client ID of type Desktop app and download client_secret.json.

2. Install and log in

# Recommended: install from PyPI
uv tool install google-chat-mcp

# Or: install from a git tag (pre-release / unreleased fixes)
# uv tool install git+https://github.com/mmedum/[email protected]

# Or: install from a local clone for dev / custom builds
# git clone https://github.com/mmedum/google-chat-mcp && cd google-chat-mcp
# uv tool install --from . google-chat-mcp

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

The login command:

• Prints the authorization URL to stdout (so it works on headless machines).
• Opens your system browser (or falls back to "paste this URL" if it can't).
• Receives the callback on 127.0.0.1:<random>, exchanges the code (PKCE + state throughout).
• Stores tokens at ~/.config/google-chat-mcp/tokens.json (0600, Fernet-encrypted).

Log out with google-chat-mcp logout — revokes the refresh token at Google and deletes local files.

3. Wire into your MCP client

Point your client at the installed binary. Both names work:

mcp-server-google-chat        # primary, matches Anthropic's mcp-server-* convention
google-chat-mcp               # alias, for discoverability

Example Claude Code entry:

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

See docs/gcp-setup.md for the full one-time flow.

HTTPS mode — shared / hosted deployment

For teams who want a shared deployment (one Google app, many users). Requires a public HTTPS hostname, Docker, and a reverse proxy in front of port 8000.

1. Required env

export GCM_BASE_URL="https://chat-mcp.example.com"
# CSV of OAuth-callback URLs your MCP client(s) use. One entry per client.
#   Claude: https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback
#   Cursor: https://cursor.com/oauth/mcp/callback
export GCM_ALLOWED_CLIENT_REDIRECTS="https://your-client.example.com/oauth/callback"

2. Secrets

mkdir -p secrets
printf '%s' 'paste client id here'     > secrets/google_client_id
printf '%s' 'paste client secret here' > secrets/google_client_secret
python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())' \
    > secrets/fernet_key
python -c 'import secrets; print(secrets.token_urlsafe(48))' \
    > secrets/jwt_signing_key
python -c 'import secrets; print(secrets.token_hex(32))' \
    > secrets/audit_pepper
chmod 600 secrets/*

Docker Compose picks these up as /run/secrets/GCM_<name> inside the container.

3. Run

docker compose up -d
docker compose logs -f mcp

compose.yml pulls the published multi-arch image (ghcr.io/mmedum/google-chat-mcp:0.2) by default — linux/amd64 + linux/arm64, published with SBOM and SLSA provenance attestations on every v*.*.* tag. For local dev builds, swap the image: line for the commented build: block in compose.yml.

4. Connect your MCP client

Add a custom connector at https://chat-mcp.example.com/mcp. The client initiates OAuth; users grant scopes once, and the client stores the MCP bearer token for subsequent tool calls.

Transport-security notes (HTTPS)

FastMCP 3.x enforces these per the MCP spec (2025-06-18). You shouldn't need to touch them, but don't disable them:

• `Origin` header validation on every request (DNS-rebinding defense).
• Localhost-only bind for dev (127.0.0.1). Use 0.0.0.0 only behind

a real reverse proxy.

• `MCP-Protocol-Version: 2025-06-18` header required; server returns

400 on invalid/missing version.

• Authentication (the FastMCP-issued JWT via GoogleProvider) is

mandatory — never expose the HTTP endpoint unauthenticated.

Local development with a tunnel (HTTPS mode)

MCP custom connectors call your /mcp endpoint from the public internet, so pure localhost doesn't work end-to-end for HTTPS-mode dev. Front it with Cloudflare Tunnel / ngrok / Tailscale Funnel.

# In one terminal
cloudflared tunnel --url http://localhost:8000
# Add the printed URL to your Google OAuth client's redirect list,
# then in another terminal:
export GCM_BASE_URL="https://<random>.trycloudflare.com"
uv run python -m src.server

Quick-tunnel URLs rotate on restart; use a named tunnel bound to a domain you own for a stable hostname.

Deployer invariants

• No image rebuild. Each deployer supplies their own Google app

credentials at runtime (mounted secrets in HTTPS, client_secret.json in stdio). Pull the published image or install from source; configure; run.

• No centralized deployment. Each deployer owns their Google app,

their tokens, and their rollout cadence. Compromises of a specific deployment's credentials or tokens are the deployer's responsibility — see docs/runbook.md for rotation procedures.

• No hardcoded client-specific logic. allowed_client_redirects

defaults to empty; operators configure it per their MCP client. The server is intentionally client-agnostic.

Architecture

MCP client ──(stdio OR HTTP)──► FastMCP
                                 ├── Tools + Resources (see table above)
                                 ├── chat_client — shared httpx.AsyncClient with retry/backoff
                                 ├── SQLite (audit_log, user_directory cache)
                                 ├── Rate limiter (60/min per user)
                                 └── Auth resolver (transport-specific)
                                     ├── HTTPS: FastMCP.GoogleProvider (PKCE, state, JWT issuance)
                                     └── stdio: local Fernet-encrypted token store

src/server.py is the HTTPS entry (builds the GoogleProvider). src/stdio.py is the stdio entry (loopback login + local token store). Both hand the shared build_app(settings, resolver=, auth=) composition root identical tool and resource registration. See docs/architecture.md for the full request-flow diagram, per-transport wiring, and the deliberate design decisions (no hand-rolled OAuth, no server-side message-body mutation, etc.).

Local development

uv sync --extra dev
uv run pytest                  # full suite, 80% coverage gate
uv run ruff check .
uv run ty check
uv run python -m src.server    # HTTPS (needs GCM_* env)
uv run python -m src.stdio login --client-secret ./client_secret.json
uv run mcp-server-google-chat  # stdio serve

Pre-commit hooks: uv run pre-commit install (includes gitleaks).

Operations

docs/runbook.md: missing-scope errors, rotation procedures for Fernet key / GCP client secret / refresh tokens, recovery from common mis-states.

Security

See SECURITY.md for how to report vulnerabilities.

Versioning and support

Tool names and I/O shapes are semver-stable from v1.0 onward. Breaking changes get a major-version bump and ship with at least one minor-version deprecation warning before removal. We support the Python versions listed in pyproject.toml under requires-python.

Code of conduct

See CODE_OF_CONDUCT.md — Contributor Covenant 3.0.

License

Apache 2.0 — see LICENSE.