# google-chat-mcp

MCP server for **Google Chat**. Lets Claude (Code / Desktop) or any MCP client list your spaces, read and search messages, pull threads and members, and — opt-in — send messages as you.

Read-only by default. Runs locally over stdio. Refresh token stored `0600` under `~/.google-chat-mcp/`.

## Tools

| Tool              | Input                                              | Notes                                                                 |
| ----------------- | -------------------------------------------------- | --------------------------------------------------------------------- |
| `list_spaces`     | `type` (all/space/group/dm), `query`, `resolveDmNames`, `limit` | Sorted by last activity. DMs have no name unless `resolveDmNames` (capped at 40 lookups). |
| `list_messages`   | `space`, `since`, `until`, `limit` ≤100, `pageToken` | Newest first. `since`/`until` filter server-side.                    |
| `search_messages` | `query` (substring or `/regex/`), `spaces?`, `since`, `until`, `limit` | Client-side scan; Chat API has no full-text search. Default window 14 days, ≤500 msgs/space. |
| `get_thread`      | `thread`                                           | All replies, oldest first.                                            |
| `list_members`    | `space`                                            | Users + roles, names/emails via People API.                           |
| `send_message`    | `space`, `text`, `thread?`                         | Only registered when `SEND_ENABLED=true`.                             |

Sender names come from the People API directory (`directory.readonly`). If that API is disabled or the user is external, you get `users/<id>` instead — everything else still works.

## Setup

Requires a **Google Workspace** account. Consumer `@gmail.com` accounts cannot call the Chat API (403).

### 1. Google Cloud project (one-time, ~10 min)

1. [console.cloud.google.com](https://console.cloud.google.com) → create/select a project.
2. **APIs & Services → Library** → enable **Google Chat API** and **People API**.
3. **Google Chat API → Configuration** tab → fill in *App name*, *Avatar URL*, *Description*; interactive features **off**; visibility to your domain. Save.
   > Gotcha: the Chat API rejects *all* OAuth calls with `403` until this form is saved, even for read-only user auth.
4. **OAuth consent screen** → *Internal* → add scopes:
   - `https://www.googleapis.com/auth/chat.spaces.readonly`
   - `https://www.googleapis.com/auth/chat.messages.readonly`
   - `https://www.googleapis.com/auth/chat.memberships.readonly`
   - `https://www.googleapis.com/auth/directory.readonly`
   - `https://www.googleapis.com/auth/chat.messages.create` (only if you want `send_message`)
5. **Credentials → Create credentials → OAuth client ID → Desktop app** → download JSON. Keep it out of any repo.

### 2. Login

```bash
export GOOGLE_CHAT_CLIENT_SECRET_PATH=/path/to/client_secret.json
npx google-chat-mcp login        # browser opens → sign in with your Workspace account
npx google-chat-mcp whoami       # sanity check
```

### 3. Register with Claude Code

```bash
claude mcp add google-chat \
  -e GOOGLE_CHAT_CLIENT_SECRET_PATH=/path/to/client_secret.json \
  -- npx -y google-chat-mcp
```

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "google-chat": {
      "command": "npx",
      "args": ["-y", "google-chat-mcp"],
      "env": { "GOOGLE_CHAT_CLIENT_SECRET_PATH": "/path/to/client_secret.json" }
    }
  }
}
```

## Environment

| Var                              | Default                          | Purpose                                     |
| -------------------------------- | -------------------------------- | ------------------------------------------- |
| `GOOGLE_CHAT_CLIENT_SECRET_PATH` | —                                | Desktop OAuth client JSON. On macOS falls back to Keychain item `jay-google-oauth`/`client`. |
| `GOOGLE_CHAT_TOKEN_PATH`         | `~/.google-chat-mcp/token.json`  | Refresh token cache.                        |
| `SEND_ENABLED`                   | `false`                          | `true` registers `send_message` and requests the create scope. Re-run `login` after changing. |

## Quota notes

Chat API: ~60 requests/min/user. Spaces and member lists are cached 5 min in-process; resolved user names are cached on disk in `~/.google-chat-mcp/users.json`. `search_messages` is the expensive one — scope it with `spaces` and `since`.

## Development

```bash
pnpm install
pnpm dev login
pnpm typecheck && pnpm lint && pnpm build
```

Node ≥ 22. TypeScript strict, ESM, `tsup` build.

## License

MIT