google-chat-mcp

MCP server for Google Chat. Lets Claude (Code / Desktop) or any MCP client list your spaces, read and search messages, pull threads and members, and — opt-in — send messages as you.

Read-only by default. Runs locally over stdio. Refresh token stored 0600 under ~/.google-chat-mcp/.

Tools

Sender names come from the People API directory (directory.readonly). If that API is disabled or the user is external, you get users/<id> instead — everything else still works.

Related MCP server: google-mcp

Setup

Requires a Google Workspace account. Consumer @gmail.com accounts cannot call the Chat API (403).

1. Google Cloud project (one-time, ~10 min)

1. console.cloud.google.com → create/select a project.

2. APIs & Services → Library → enable Google Chat API and People API.

3. Google Chat API → Configuration tab → fill in App name, Avatar URL, Description; interactive features off; visibility to your domain. Save.

   Gotcha: the Chat API rejects all OAuth calls with 403 until this form is saved, even for read-only user auth.

4. OAuth consent screen → Internal → add scopes:

   • https://www.googleapis.com/auth/chat.spaces.readonly

   • https://www.googleapis.com/auth/chat.messages.readonly

   • https://www.googleapis.com/auth/chat.memberships.readonly

   • https://www.googleapis.com/auth/directory.readonly

   • https://www.googleapis.com/auth/chat.messages.create (only if you want send_message)

5. Credentials → Create credentials → OAuth client ID → Desktop app → download JSON. Keep it out of any repo.

2. Login

export GOOGLE_CHAT_CLIENT_SECRET_PATH=/path/to/client_secret.json
npx google-chat-mcp login        # browser opens → sign in with your Workspace account
npx google-chat-mcp whoami       # sanity check

3. Register with Claude Code

claude mcp add google-chat \
  -e GOOGLE_CHAT_CLIENT_SECRET_PATH=/path/to/client_secret.json \
  -- npx -y google-chat-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "google-chat": {
      "command": "npx",
      "args": ["-y", "google-chat-mcp"],
      "env": { "GOOGLE_CHAT_CLIENT_SECRET_PATH": "/path/to/client_secret.json" }
    }
  }
}

Environment

Quota notes

Chat API: ~60 requests/min/user. Spaces and member lists are cached 5 min in-process; resolved user names are cached on disk in ~/.google-chat-mcp/users.json. search_messages is the expensive one — scope it with spaces and since.

Development

pnpm install
pnpm dev login
pnpm typecheck && pnpm lint && pnpm build

Node ≥ 22. TypeScript strict, ESM, tsup build.

License

MIT