better-workspace-mcp

<h1 align="center">better-workspace-mcp</h1>

<p align="center">
  <strong>Google Workspace MCP — Docs, Drive, Calendar, Gmail, Sheets, Slides, Tasks, Chat, People, Forms</strong>
</p>

<p align="center">
  <a href="https://github.com/n24q02m/better-workspace-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/n24q02m/better-workspace-mcp/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://github.com/n24q02m/better-workspace-mcp/actions/workflows/cd.yml"><img alt="CD" src="https://github.com/n24q02m/better-workspace-mcp/actions/workflows/cd.yml/badge.svg"></a>
  <a href="https://codecov.io/gh/n24q02m/better-workspace-mcp"><img alt="codecov" src="https://codecov.io/gh/n24q02m/better-workspace-mcp/graph/badge.svg"></a>
  <a href="https://github.com/n24q02m/better-workspace-mcp/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/n24q02m/better-workspace-mcp?display_name=tag&sort=semver"></a>
  <a href="https://github.com/python-semantic-release/python-semantic-release"><img alt="semantic-release" src="https://img.shields.io/badge/semantic--release-e10079?logo=semantic-release&logoColor=white"></a>
  <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/github/license/n24q02m/better-workspace-mcp"></a>
</p>

<p align="center">
  <a href="https://mcp.n24q02m.com">Docs</a> ·
  <a href="#install">Install</a> ·
  <a href="#quick-start">Quick start</a> ·
  <a href="https://github.com/n24q02m/better-workspace-mcp/discussions">Community</a>
</p>

<!-- BEGIN: AUTO-GENERATED-CROSS-PROMO -->
<details>
  <summary><strong>Sister projects from n24q02m</strong> (click to expand)</summary>

| Project | Tagline | Tag |
|---|---|---|
| [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor... | Tooling |
| [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |
| [better-drive](https://github.com/n24q02m/better-drive) | 2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray | Tooling |
| [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP |
| [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP |
| [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP |
| [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | Drop-in python-semantic-release fork with built-in release-safety guards (orp... | Tooling |
| [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |
| [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP |
| [claude-plugins](https://github.com/n24q02m/claude-plugins) | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace |
| [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP |
| [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |
| [mcp-core](https://github.com/n24q02m/mcp-core) | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP |
| [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |
| [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library |
| [skret](https://github.com/n24q02m/skret) | Secrets without the server. | CLI |
| [tacet](https://github.com/n24q02m/tacet) | A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... | Tooling |
| [web-core](https://github.com/n24q02m/web-core) | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |
| [wet-mcp](https://github.com/n24q02m/wet-mcp) | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |

</details>
<!-- END: AUTO-GENERATED-CROSS-PROMO -->

## Table of contents

- [Install](#install)
- [Remote (HTTP mode)](#remote-http-mode)
- [Tools](#tools)
- [Quick start](#quick-start)
- [Multi-account](#multi-account)
- [Documentation](#documentation)
- [Handover](docs/HANDOVER.md)
- [Contributing](#contributing)
- [License](#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:

```jsonc
{
  "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](https://console.cloud.google.com/apis/credentials)
under APIs & Services → Credentials. Desktop is the right type because the server
receives the consent redirect on a
[loopback address](https://developers.google.com/identity/protocols/oauth2/native-app),
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).

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

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

| Mode | Selected by | Serves | Google OAuth client |
| --- | --- | --- | --- |
| `stdio` | the default | one user, on their own machine | **Desktop app** |
| `http` | `--http`, `MCP_TRANSPORT=http`, or `TRANSPORT_MODE=http` | several users, one credential bucket per JWT `sub` | **Web application** |

### 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`:

| Redirect URI | Used by |
| --- | --- |
| `<PUBLIC_URL>/callback` | signing in to the server itself (delegated OAuth) |
| `<PUBLIC_URL>/accounts/callback` | `config(action="account_add")` -- adding a second Google account |

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

| Variable | Required | What it does |
| --- | --- | --- |
| `GOOGLE_OAUTH_CLIENT_ID` | yes | Web client id. The server refuses to start without it. |
| `GOOGLE_OAUTH_CLIENT_SECRET` | yes | Web client secret. Same. |
| `CREDENTIAL_SECRET` | yes | Derives each subject's credential-encryption key, and the JWT signing key. Without it that signing key would land on a container filesystem that does not survive a restart, so the server refuses to start rather than lose everyone's session on the next deploy. |
| `PUBLIC_URL` | in practice | The exact public origin, e.g. `https://<your-host>`. It is what the redirect URIs above are built from; unset, the server falls back to the `Host` header and the redirect stops matching what Google has registered. |
| `MCP_RELAY_PASSWORD` | recommended | One shared password gating `/authorize` behind a login page. Empty disables the gate, which leaves anyone who can reach the host able to start an OAuth flow against your deployment. |
| `PORT` | no | Listen port. `0` (the default) asks the OS for a free one. |
| `HOST` | no | Bind address. Defaults to loopback, so a container needs `0.0.0.0`. |
| `MCP_STORAGE_BACKEND` / `MCP_KV_BASE_URL` | Cloudflare only | Set to `cf-kv` and the worker's internal KV URL when running as a Cloudflare Worker + Container. Left unset, credentials are stored on local disk. |

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

| Tool | What it covers |
| --- | --- |
| `docs` | Google Docs -- `getText`, `create`, `writeText`, `getSuggestions`, `replaceText`, `formatText` |
| `dri