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