Google Chat MCP Server

A custom MCP (Model Context Protocol) server that connects Claude AI to Google Chat. It fills a gap in the Claude ecosystem: Claude has built-in connectors for Slack and Microsoft Teams, but nothing for Google Chat.

Deploy this server and your team can use Claude's "Ask Your Org" enterprise search feature against Google Chat — listing spaces, fetching messages, and searching conversations.

How it works

User asks a question in Claude ("Ask Your Org")
        ↓
Claude determines it needs to check Google Chat
        ↓
Claude calls this MCP server over HTTPS
        ↓
MCP server translates the request into a Google Chat API call
        ↓
Google Chat API returns messages (respecting user's permissions)
        ↓
MCP server passes the data back to Claude
        ↓
Claude synthesizes an answer for the user

MCP Tools

Tool	Description
list_spaces	Returns all Google Chat spaces the user belongs to
get_messages	Fetches messages from a space within a date range
search_messages	Searches for messages containing specific text in a space

All access is read-only. The server cannot send messages, delete anything, or modify any Google Chat data.

Access Control

Each user authenticates individually with their own Google account via OAuth 2.0. The server uses per-user tokens — Claude can only access spaces and messages the requesting user already has access to in Google Chat.

Tech Stack

• Language: Python 3.12+
• Framework: FastMCP (MCP Python SDK)
• Google API: Google Chat API v1 via google-api-python-client
• Auth: OAuth 2.0 with PKCE and Dynamic Client Registration (RFC 7591), per-user tokens
• Hosting: AWS EC2 behind Nginx reverse proxy with HTTPS
• Transport: Streamable HTTP

Quick Start

1. Set up Google Cloud credentials — See docs/gcp-setup.md. Don't skip Step 5 (Chat app configuration) — the API won't work without it.
2. Deploy to a server with HTTPS — See docs/deployment.md
3. Connect in Claude — See docs/claude-integration.md

Prerequisites

Requirement	Notes
Google Workspace account	Same org that uses Google Chat
Google Cloud project	With Google Chat API enabled + Chat app configured
OAuth 2.0 credentials (Web app)	Client ID + Secret from GCP
HTTPS endpoint	Public domain with SSL — required by Claude
MySQL database	For storing per-user OAuth tokens
Claude Team/Enterprise plan	With Owner access to add custom connectors

Environment Variables

Copy .env.example to .env and fill in all values:

Variable	Description
GOOGLE_CLIENT_ID	OAuth client ID from Google Cloud Console
GOOGLE_CLIENT_SECRET	OAuth client secret from Google Cloud Console
GOOGLE_REDIRECT_URI	Must be https://your-domain.com/callback
DB_HOST	MySQL host
DB_PORT	MySQL port (default: 3306)
DB_NAME	Database name (e.g. gchat_mcp)
DB_USER	MySQL username
DB_PASSWORD	MySQL password
SERVER_BASE_URL	Public HTTPS URL of this server (e.g. https://your-domain.com)
SERVER_HOST	Bind host (default: 0.0.0.0)
SERVER_PORT	Bind port (default: 8000)

Running Tests

python -m pytest tests/ -v

Tests mock all external dependencies — no database or Google credentials needed.

Known Limitations

• MySQL required: There is no SQLite option currently. The database dependency adds friction for local development. See CONTRIBUTING.md for how to contribute an alternative.
• Single-instance only: OAuth state is stored in memory, so running multiple server instances is not supported without a shared state backend.
• Message cap: get_messages and search_messages cap results at 500 messages per request. Use a narrower date range for complete results.

Troubleshooting

"Couldn't reach the MCP server" in Claude

Claude.ai requires OAuth Dynamic Client Registration (RFC 7591). Before starting the OAuth flow, Claude POSTs to /register to obtain a client_id. The server must expose this endpoint and advertise it via /.well-known/oauth-authorization-server. Without it, Claude fails silently — the user never gets a login redirect. This is already implemented in src/auth.py.

Google Chat API calls fail even with the API enabled

The Chat API requires a Chat app to be configured in Google Cloud Console (APIs & Services → Google Chat API → Configuration tab) before any API calls work — even read-only ones. See docs/gcp-setup.md Step 5.

Local development tunneling

Use ngrok for local testing with Claude.ai. Cloudflare's trycloudflare.com domains are blocked by Claude.ai's backend servers. ngrok works, but has a browser interstitial on the free tier — visit your ngrok URL in the browser and click "Visit Site" once before initiating the Claude connector flow. See docs/deployment.md for the full local dev setup.

HTTP 400 "Invalid filter query" from Google Chat API

The spaces.messages.list API only accepts > and < for createTime filters — >= returns HTTP 400. This is already fixed in src/google_chat.py.

Contributing

See CONTRIBUTING.md. Please read our Code of Conduct before contributing.

License

MIT — Copyright (c) 2026 ColoredCow