google-mcp

google-mcp

A Model Context Protocol 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, 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

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

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

4. Authorize once

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

{
  "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.

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 and NOTICE.