# Google Chat MCP Server

An [MCP](https://modelcontextprotocol.io) server that exposes Google Chat as
tools for an LLM client (Claude Desktop, Claude Code, etc.): sending
messages, listing spaces, and searching message history.

## Tools

| Tool | Description |
| --- | --- |
| `send_message(space, text, thread_key=None)` | Post a message to a space, optionally inside an existing thread. |
| `list_spaces(page_size=100, page_token=None)` | List spaces the configured account can see. |
| `list_messages(space, page_size=50, page_token=None, filter_expr=None)` | List recent messages in a space, newest first. |
| `search_messages(space, query, page_size=50)` | Substring-search a space's recent messages (client-side, since the Chat API has no full-text search endpoint). |

## Setup

1. Create a Google Cloud project and enable the **Google Chat API**.
2. Create a service account and download its JSON key.
3. To use `list_spaces` / `list_messages` / `search_messages`, enable
   [domain-wide delegation](https://support.google.com/a/answer/162106) for
   the service account in your Google Workspace admin console, granting the
   scopes in `src/google_chat_mcp/auth.py`. `send_message` alone works with
   a bare service account registered as a Chat app.
4. Copy `.env.example` to `.env` and fill in the path to your key file
   (and the user to impersonate, if needed).

```bash
uv sync
cp .env.example .env  # then edit it
```

## Running

```bash
uv run google-chat-mcp
```

### Claude Desktop / Claude Code config

```json
{
  "mcpServers": {
    "google-chat": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/google-chat-mcp", "run", "google-chat-mcp"],
      "env": {
        "GOOGLE_CHAT_SERVICE_ACCOUNT_FILE": "/absolute/path/to/service-account.json",
        "GOOGLE_CHAT_IMPERSONATED_USER": "someone@yourdomain.com"
      }
    }
  }
}
```

## Project layout

- `auth.py` — builds an authenticated Google Chat API client from a service
  account key, with optional domain-wide-delegation impersonation.
- `chat_client.py` — thin wrapper over the `chat` v1 REST API (send, list,
  search).
- `server.py` — MCP tool definitions built on the official Python SDK.