google-chat-mcp

MCP server for Google Chat — manage spaces, messages, members, reactions, attachments, and GIFs through the Model Context Protocol.

Features

• 19 MCP tools covering the full Google Chat API
• Spaces — list, get, create, update, delete
• Messages — list (newest first), get, send, reply to threads, update, delete
• Members — list, add, remove, get user info
• Reactions — add, remove
• Attachments — get metadata, upload files with messages
• Two transports — stdio and HTTP/SSE
• Automatic OAuth — browser-based flow, token caching + auto-refresh
• Smart formatting — concise human-readable responses, automatic user name resolution

Setup

1. Google Cloud Project & Chat API Setup

Create Project & Enable API

1. Go to Google Cloud Console
2. Create a new project (or select existing)
3. Go to APIs & Services > Library
4. Search for "Google Chat API" and click Enable

Configure the Chat App

This step is required — without it, the Chat API won't work.

1. After enabling the Google Chat API, click on it to open its settings
2. Go to the Configuration tab
3. Fill in the following:
   • App name — give it a name (e.g. "Chat MCP Assistant")
   • Avatar URL — optional, any image URL for the app icon
   • Description — a short description (e.g. "MCP server for Google Chat")
   • Enable Interactive features — toggle ON
   • Functionality — check "Receive 1:1 messages" and "Join spaces and group conversations"
   • Connection settings — select "Apps Script project" (this won't actually be used, but a selection is required)
   • Visibility — choose who can use the app:
     • For personal use: select your own account
     • For team use: select your Google Workspace domain
4. Click Save

Create OAuth Credentials

1. Go to APIs & Services > Credentials
2. Click Create Credentials > OAuth client ID
3. If prompted, configure the OAuth consent screen first:
   • Choose Internal (for Workspace) or External (for personal Gmail)
   • Fill in app name and your email
   • Add these scopes: chat.spaces, chat.messages, chat.memberships, chat.messages.reactions, userinfo.profile, directory.readonly
   • Save and continue through the remaining steps
4. Back on Credentials, click Create Credentials > OAuth client ID
5. Choose Desktop app or Web application
   • If Web application: add http://localhost:18273/auth/callback as an authorized redirect URI (or any http://localhost:{port}/{path} — the server reads it from your credentials file)
   • If Desktop app: no redirect URI needed
6. Download the JSON and save it as credentials.json

2. Install & Run

# Run directly with npx (no install needed)
npx google-chat-mcp --credentials-path ./credentials.json

# Or install globally
npm install -g google-chat-mcp
google-chat-mcp --credentials-path ./credentials.json

# HTTP/SSE transport
npx google-chat-mcp --transport http --port 3000 --credentials-path ./credentials.json

On first run, your browser will open for Google authentication. Approve access and the token is cached automatically.

3. Connect to AI Agents

Claude Code (CLI)

claude mcp add google-chat -- npx google-chat-mcp --credentials-path /absolute/path/to/credentials.json

Add -s user to make it available across all projects:

claude mcp add google-chat -s user -- npx google-chat-mcp --credentials-path /absolute/path/to/credentials.json

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "google-chat": {
      "command": "npx",
      "args": [
        "google-chat-mcp",
        "--credentials-path",
        "/absolute/path/to/credentials.json"
      ]
    }
  }
}

Cursor

Add to Cursor's MCP settings (Settings > MCP Servers):

{
  "google-chat": {
    "command": "npx",
    "args": [
      "google-chat-mcp",
      "--credentials-path",
      "/absolute/path/to/credentials.json"
    ]
  }
}

Windsurf / Continue / Other MCP Clients

Any MCP client that supports stdio transport can connect. Use:

• Command: npx
• Args: google-chat-mcp --credentials-path /absolute/path/to/credentials.json

For HTTP/SSE clients, run with --transport http --port 3000 and connect to http://localhost:3000/sse.

CLI Options

Flag	Default	Description
--transport	stdio	Transport mode: stdio or http
--port	3000	Port for HTTP transport
--credentials-path	./credentials.json	Path to OAuth credentials file
--token-path	./token.json	Path to stored token
--disable-token-saving	false	Don't persist tokens to disk

Tools

Spaces

Tool	Description
list_spaces	List all accessible spaces (concise format, configurable pageSize)
get_space	Get full details of a specific space
create_space	Create a new space
update_space	Update space display name or description
delete_space	Delete a space

Messages

Tool	Description
list_messages	List messages newest-first with sender names resolved. Supports date filtering (local timezone) and pageSize
get_message	Get a specific message with sender name resolved
send_message	Send a text message to a space
reply_to_thread	Reply to an existing thread
update_message	Update a message's text
delete_message	Delete a message

Members

Tool	Description
list_members	List members with display names resolved
add_member	Add a user to a space
remove_member	Remove a member from a space
get_user_info	Look up a user's display name, email, and photo

Reactions

Tool	Description
add_reaction	Add an emoji reaction to a message
remove_reaction	Remove a reaction

Attachments

Tool	Description
get_attachment	Get attachment metadata and download URL
upload_attachment	Upload a file and send it as a message

OAuth Scopes

The server requests these Google OAuth scopes:

• chat.spaces — read/write spaces
• chat.messages — read/write messages
• chat.memberships — read/write memberships
• chat.messages.reactions — read/write reactions
• userinfo.profile — authenticated user profile
• directory.readonly — workspace user directory (for name resolution)

Troubleshooting

redirect_uri_mismatch error

Your OAuth credentials have a registered redirect URI that doesn't match. The server reads the redirect URI from your credentials.json automatically. Make sure the URI registered in Google Cloud Console matches what's in the file.

User names showing as users/123456...

The People API may not resolve names depending on your Google Workspace privacy settings. The server caches display names from Chat API responses (members, message senders) as a fallback.

Token expired

Delete your token.json file and restart — the browser auth flow will re-trigger.

Development

npm install
npm run build
npm test

License

MIT