# google-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server for Google Workspace with **pluggable transports** — run it **locally over stdio** or **remotely over HTTP** (so you can reach it from a phone). It ships with **Google Chat** today and is structured so Gmail, Drive, and Calendar can be added as additional modules.

You bring your own Google Cloud OAuth client and authorize once. The server then exposes Chat tools to any MCP client (Claude, Claude Code, etc.).

## Transports

The server selects a transport at startup — by CLI arg or the `GOOGLE_MCP_TRANSPORT` env var. Adding a transport means implementing one `TransportRunner` and registering it; nothing else changes (Open/Closed).

| Transport | Command | Use |
|---|---|---|
| `stdio` | `google-mcp serve stdio` (default) | Local MCP client on the same machine |
| `http` | `google-mcp serve http` | Remote / phone access over HTTP |

The HTTP transport listens on `PORT` (default `8080`) at `GOOGLE_MCP_HTTP_PATH` (default `/mcp`). Set `GOOGLE_MCP_BEARER_TOKEN` to require an `Authorization: Bearer <token>` header.

## Tools

| Tool | Description |
|---|---|
| `chat_list_spaces` | List spaces and direct messages the user belongs to. |
| `chat_list_messages` | List messages in a space. |
| `chat_find_messages` | Find messages in a space by case-insensitive text match. |
| `chat_send_message` | Post a text message to a space. |

## Why not the official Google Chat MCP server?

Google offers a hosted Chat MCP server at `chatmcp.googleapis.com`, but it is in Developer Preview and gated behind program enrollment. `google-mcp` runs locally, uses scopes you control, and is easy to extend to other Workspace APIs.

## Prerequisites

- Node.js >= 20
- A Google Cloud project with the **Google Chat API** enabled
- An OAuth client (type: **Desktop app**) for the loopback authorization flow

## Setup

### 1. Create an OAuth client

1. In [Google Cloud Console](https://console.cloud.google.com/), enable the **Google Chat API**.
2. Configure the OAuth consent screen (External or Internal).
3. Create credentials → OAuth client ID → **Desktop app**.
4. Note the client ID and client secret.

### 2. Install and build

```bash
git clone https://github.com/thehellmaker/google-mcp.git
cd google-mcp
npm install
npm run build
```

### 3. Provide credentials

Copy `.env.example` to `.env` (or export the variables in your shell):

```bash
export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
```

### 4. Authorize once

```bash
npm run auth
```

This opens a loopback authorization flow. Approve access in your browser. A refresh token is stored at `~/.config/google-mcp/token.json` (mode `0600`).

## Use with Claude / Claude Code

Add to your MCP client config (paths and env are illustrative):

```json
{
  "mcpServers": {
    "google": {
      "command": "node",
      "args": ["/absolute/path/to/google-mcp/dist/index.js"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

## Remote access (phone)

A local stdio server can only be reached from the same machine. To trigger tools from a phone, run the **HTTP transport** on a host the Claude app can reach over HTTPS, and add it as a custom connector.

```bash
GOOGLE_MCP_TRANSPORT=http PORT=8080 GOOGLE_MCP_BEARER_TOKEN="$(openssl rand -hex 32)" npm run start:http
```

Then put it behind HTTPS. Options, simplest first:

- **Tunnel (quick test):** `cloudflared tunnel --url http://localhost:8080` or `ngrok http 8080` gives a public HTTPS URL.
- **Single small host:** Fly.io, Railway, Render, or a cheap VPS running the container/process behind a TLS reverse proxy (Caddy/Traefik).
- **Behind an MCP gateway:** put it behind an existing open-source MCP gateway (Pomerium, Obot, Microsoft `mcp-gateway`, Docker MCP Gateway) when you want OAuth, per-tool policy, and audit logging without writing them yourself.

> Note on auth: the built-in bearer token is the minimal guard. Claude's custom-connector UI expects either an open server or full OAuth — a fronting gateway is the clean way to add OAuth to a remote deployment.

## OAuth scopes

```
https://www.googleapis.com/auth/chat.spaces.readonly
https://www.googleapis.com/auth/chat.messages.readonly
https://www.googleapis.com/auth/chat.messages.create
https://www.googleapis.com/auth/chat.memberships.readonly
```

## Security

- No credentials are committed. `.env`, `token.json`, and `credentials.json` are gitignored.
- The refresh token lives only on your machine under `~/.config/google-mcp/`.
- The server inherits exactly the permissions your OAuth consent grants — nothing more.

## Adding a new Workspace module

1. Create `src/modules/<name>/index.ts` exporting a `ToolModule` (`name`, `scopes`, `register`).
2. Add it to the array in `src/modules/registry.ts`.

Scopes are aggregated automatically for the `auth` flow.

## License

Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).