better-workspace-mcp

Google Workspace MCP — Docs, Drive, Calendar, Gmail, Sheets, Slides, Tasks, Chat, People, Forms

Docs · Install · Quick start · Community

Table of contents

• Install
• Remote (HTTP mode)
• Tools
• Quick start
• Multi-account
• Documentation
• Contributing
• License

Install

The server runs in two modes: stdio (default, single-user, one Google OAuth client of your own) and HTTP (multi-user, OAuth 2.1 delegated to Google). For stdio, add it to your MCP client config:

{
  "mcpServers": {
    "better-workspace": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/better-workspace-mcp@latest"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "<your-client-id>.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "<your-client-secret>"
      }
    }
  }
}

Those two values come from an OAuth 2.0 client of type Desktop app, created in the Google Cloud Console under APIs & Services → Credentials. Desktop is the right type because the server receives the consent redirect on a loopback address, not on a public URL. Enable the Workspace APIs you plan to call on the same project, and add yourself as a test user while the consent screen is unpublished.

The first run opens the Google consent screen in your browser; the refresh token is stored encrypted on your machine, so later runs start without asking again.

The same server can also serve several people over HTTP -- see Remote (HTTP mode).

Remote (HTTP mode)

Besides stdio, the server runs as a multi-user HTTP service. Authentication is OAuth 2.1 delegated to Google, and each user's Google credentials are kept in their own bucket keyed by their JWT sub, so one deployment serves several people without them sharing an account.

Point your MCP client at the host you deployed it on:

{
  "mcpServers": {
    "better-workspace": {
      "type": "http",
      "url": "https://<your-host>/mcp"
    }
  }
}

Modes

Two, and only two. There is no proxy or daemon mode: stdio speaks the MCP stdio transport directly, with no HTTP hop inside it.

Two OAuth clients, not one

Google binds redirect URIs to the type of the OAuth client, so the two modes cannot share one:

• A Desktop client may redirect to any loopback port. That is what stdio needs -- it stands a throwaway consent server on a random port.
• A Web client may only redirect to URIs registered in advance. That is what a deployment needs, because a public host has no loopback to come back to.

Register both of these on the Web client, or the flows that use them fail with redirect_uri_mismatch:

Keep the two client credentials under separate names. Pointing GOOGLE_OAUTH_CLIENT_ID/_SECRET at the Web client on a machine that also runs stdio breaks every stdio install, which is why the Cloudflare deploy carries the Web pair as GOOGLE_OAUTH_WEB_CLIENT_ID/_SECRET and renames it on the way into the container (src/worker.ts).

Environment

docker-compose.http.yml in this repo is these variables written out as a runnable overlay.

Tools

One composite tool per Workspace domain, plus config and help: