Better Workspace MCP

workspace

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

ARCHIVED 2026-09-13 — This repository is no longer maintained. Use the official Google Workspace APIs instead of this MCP server. Existing installations keep working but receive no updates or support.

Docs · Install · Quick start · Community

Sister projects from n24q02m (click to expand)

Table of contents

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

Install

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

{

"mcpServers": { "workspace": { "command": "npx", "args": ["--yes", "@n24q02m/workspace@latest"], "env": { "GOOGLE_OAUTH_CLIENT_ID": " .apps.googleusercontent.com", "GOOGLE_OAUTH_CLIENT_SECRET": " " } } } }

The package is @n24q02m/workspace (formerly @n24q02m/better-workspace-mcp; old package receives one final release then freezes). The MCP Registry id stays io.github.n24q02m/better-workspace-mcp, and the legacy better-workspace-mcp command is kept as an alias of workspace.

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 under ~/.better-workspace/ (a legacy ~/.better-workspace-mcp/ is read as a fallback), so later runs start without asking again.

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

Install with an AI agent -- paste this to your AI coding agent:

Install MCP server workspace following the steps at

https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-workspace-mcp/setup-with-agent.md

Remote (HTTP mode)

Besides stdio, the server runs as a multi-user HTTP service. Each request carries a bearer token from a users file (WORKSPACE_USERS_FILE), and each user's Google credentials are kept in their own bucket, keyed by that user's namespace, so one deployment serves several people without them sharing an account. Google consent for an HTTP account runs on the host, with workspace auth --user .

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

{

"mcpServers": { "workspace": { "type": "http", "url": "https:// /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. stdio uses a Desktop client, which may redirect to any loopback port. HTTP uses a Web client. Keep the two 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. That is why docker-compose.http.yml reads the Web pair as GOOGLE_OAUTH_WEB_CLIENT_ID/_SECRET and renames it on the way into the container.

Environment

Credentials are stored on local disk under ~/.better-workspace/, which is the data volume in the container. A legacy ~/.better-workspace-mcp/ is read as a fallback.

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:

Questions are added to a form with forms(action="batchUpdate"), not at create; responses are read-only, because the Forms API cannot write one. Listing or deleting forms goes through drive.

Quick start

Check that the credentials landed, with the config tool. Before the first consent this reports awaiting_setup; afterwards it names the account the server is acting as:

{ "action": "status" }

Then call a domain tool. On docs, create returns the new document's ID, which getText reads back:

{ "action": "create", "title": "Notes", "content": "First line." }

{ "action": "getText", "documentId": " " }

time, config, and help need no Google account, so they answer even before consent -- time is the quickest check that