google-chat-mcp

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