# 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](https://console.cloud.google.com/)
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

```bash
# 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)

```bash
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:

```bash
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):

```json
{
  "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):

```json
{
  "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

```bash
npm install
npm run build
npm test
```

## License

MIT