google-chat-mcp

An MCP (Model Context Protocol) server that connects Claude to your Google Chat workspace — search spaces, DMs, and full message history. All sender and member names are automatically resolved to real display names via the Google People/Directory API.

Each user authenticates with their own Google account. No shared credentials files, no admin access required.

---

What you can do with it

• Search your full message history across all spaces and DMs
• Ask Claude questions like "what did the team decide about X?", "find the doc Sarah shared in the eng channel", "what were we discussing last week about the API?"
• Browse spaces, read recent messages, see who's in a given space — with real names, not user IDs
• Ask "who have I spoken to in the last 3 days?" and get a named list
• Works with Cursor, Claude Code, Claude Desktop, and Cowork

---

Setup

Quick install (one command)

git clone https://github.com/ROKT/google-chat-mcp-yash.git && cd google-chat-mcp-yash && pipx install -e . && google-chat-mcp setup --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with the values from 1Password or a teammate.

Don't have pipx? Run brew install pipx first.

What setup does

1. Saves your credentials locally to ~/.config/google-chat-mcp/env.json
2. Automatically configures ~/.cursor/mcp.json
3. Opens a browser for Google OAuth — sign in with your Rokt account

That's it. Reload Cursor (Cmd+Shift+P → Developer: Reload Window) and start chatting.

Interactive setup (if you prefer)

google-chat-mcp setup
# Prompts for Client ID and Client Secret interactively

---

Usage

Once connected, just ask Claude naturally:

What you want	What to ask
Search history	"Search my Google Chat for any messages about the Q4 budget"
Find a decision	"What did we decide about the API versioning policy?"
Find a doc that was shared	"Did anyone share a link to the new design doc in the product channel?"
Recent activity	"What was discussed in the engineering space last week?"
Who's in a space	"Who's in the #data-platform space?"
Browse spaces	"Show me all my Google Chat spaces"
Recent conversations	"Who have I spoken to in the last 3 days?"
Send a message	"Send 'heading out for lunch' to my DM with Caroline"

---

Available MCP tools

Read

Tool	Description
gchat_list_spaces	List all spaces, group chats, and DMs
gchat_search_messages	Search messages across all or specific spaces
gchat_get_space_messages	Get recent messages from one space
gchat_get_space_members	List members of a space (with real display names)
gchat_get_space	Get details of a specific space
gchat_get_message	Get a single message by resource name
gchat_get_member	Get details of a specific member

Write

Tool	Description
gchat_send_message	Send a text message to a space or DM
gchat_delete_message	Delete a message

All tools return real display names for senders and members — no raw user IDs.

---

Other MCP clients

The setup command auto-configures Cursor. For other clients, add manually:

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "google-chat": {
      "command": "google-chat-mcp",
      "args": ["serve"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "google-chat": {
      "command": "google-chat-mcp",
      "args": ["serve"]
    }
  }
}

For Claude Code and Claude Desktop, the serve command automatically loads saved credentials from ~/.config/google-chat-mcp/env.json — no env block needed.

Cowork

Copy skill/SKILL.md to your Cowork skills folder.

---

Commands

google-chat-mcp setup    # One-time setup (saves creds, configures Cursor, authenticates)
google-chat-mcp auth     # Re-authenticate with Google
google-chat-mcp serve    # Start MCP server (called automatically by MCP clients)
google-chat-mcp logout   # Revoke cached token

---

OAuth Scopes

Scope	Purpose
chat.spaces.readonly	List spaces and DMs
chat.messages.readonly	Read message history
chat.messages.create	Send new messages
chat.messages	Delete messages
chat.memberships.readonly	Read space membership
directory.readonly	Resolve user IDs → real names via Google People API

---

Troubleshooting

No credentials found — Run google-chat-mcp setup to save your credentials.

Connection closed in Cursor — Run which google-chat-mcp and check the path matches what's in ~/.cursor/mcp.json. Re-run google-chat-mcp setup to fix.

Error 403 — Your Google Workspace may restrict Chat or People API access. Ask your admin.

Token expired — Run google-chat-mcp auth to refresh.

Force re-authentication — google-chat-mcp logout && google-chat-mcp auth

---

Privacy & security

• All authentication is handled by Google OAuth 2.0 — your password is never stored
• Read and write scopes are requested — Claude can search messages and send on your behalf (always with your confirmation)
• Your token is stored locally at ~/.config/google-chat-mcp/token.json
• OAuth client credentials are stored locally at ~/.config/google-chat-mcp/env.json
• Nothing is sent to any third-party server — the MCP server runs entirely on your machine

---

License

MIT