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)| Project | Tagline | Tag |
|---|---|---|
| agent-chat-plugin | Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor... | Tooling |
| better-code-review-graph | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |
| better-drive | 2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray | Tooling |
| better-email-mcp | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP |
| better-godot-mcp | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP |
| better-notion-mcp | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP |
| better-semantic-release | Drop-in python-semantic-release fork with built-in release-safety guards (orp... | Tooling |
| better-telegram-mcp | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |
| better-workspace-mcp | Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP |
| claude-plugins | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace |
| imagine-mcp | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP |
| jules-task-archiver | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |
| mcp-core | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP |
| mnemo-mcp | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |
| qwen3-embed | Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library |
| skret | Secrets without the server. | CLI |
| tacet | A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... | Tooling |
| web-core | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |
| wet-mcp | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |
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 OAuthclient of your own) and HTTP (multi-user, OAuth 2.1 delegated to Google). Forstdio, add it to your MCP client config:
{
"mcpServers": {
"workspace": {
"command": "npx",
"args": ["--yes", "@n24q02m/workspace@latest"],
"env": {
"GOOGLE_OAUTH_CLIENT_ID": "<your-client-id>.apps.googleusercontent.com",
"GOOGLE_OAUTH_CLIENT_SECRET": "<your-client-secret>"
}
}
}
}
The package is @n24q02m/workspace (formerly @n24q02m/better-workspace-mcp;old package receives one final release then freezes). The MCP Registry id staysio.github.n24q02m/better-workspace-mcp, and the legacy better-workspace-mcpcommand is kept as an alias of workspace.
Those two values come from an OAuth 2.0 client of type Desktop app, created inthe Google Cloud Consoleunder APIs & Services → Credentials. Desktop is the right type because the serverreceives the consent redirect on aloopback address,not on a public URL. Enable the Workspace APIs you plan to call on the sameproject, 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 tokenis stored encrypted on your machine, so later runs start without asking again.
The same server can also serve several people over HTTP -- seeRemote (HTTP mode).
Install with an AI agent -- paste this to your AI coding agent:
Install MCP server
workspacefollowing the steps athttps://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. Authentication isOAuth 2.1 delegated to Google, and each user's Google credentials are kept intheir own bucket keyed by their JWT sub, so one deployment serves severalpeople without them sharing an account.
Point your MCP client at the host you deployed it on:
{
"mcpServers": {
"workspace": {
"type": "http",
"url": "https://<your-host>/mcp"
}
}
}
Modes
Two, and only two. There is no proxy or daemon mode: stdio speaks the MCP stdiotransport 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 modescannot share one:
- A Desktop client may redirect to any loopback port. That is what stdioneeds -- it stands a throwaway consent server on a random port.
- A Web client may only redirect to URIs registered in advance. That is whata 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 withredirect_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. PointingGOOGLE_OAUTH_CLIENT_ID/_SECRET at the Web client on a machine that also runsstdio breaks every stdio install, which is why docker-compose.http.yml reads theWeb pair as GOOGLE_OAUTH_WEB_CLIENT_ID/_SECRET and renames it on the way intothe container.
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. |
Credentials are stored on local disk, under the data volume.
docker-compose.http.yml in this repo is these variables written out as arunnable 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 |
drive |
Files and folders -- search, findFolder, createFolder, moveFile, renameFile, trashFile, downloadFile, getComments |
calendar |
Events -- listCalendars, listEvents, getEvent, createEvent, updateEvent, deleteEvent, respondToEvent, findFreeTime |
gmail |
Mail -- search, get, send, createDraft, sendDraft, modify, batchModify, modifyThread, downloadAttachment, listLabels, createLabel |
sheets |
Spreadsheets, read-only -- getText, getRange, getMetadata |
slides |
Presentations -- 19 actions covering slides, text, shapes, images, tables, and speaker notes |
tasks |
Task lists and tasks -- listTaskLists, listTasks, createTask, updateTask, completeTask, deleteTask |
chat |
Google Chat -- listSpaces, findSpaceByName, setUpSpace, getMessages, listThreads, sendMessage, sendDm, findDmByEmail |
people |
Profile lookups -- getMe, getUserProfile, getUserRelations |
forms |
Forms -- create, get, batchUpdate, listResponses, getResponse |
time |
Local date/time/timezone helpers (no Google account needed) |
config |
Credential state and account management |
help |
Full documentation for any tool |
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 ordeleting forms goes through drive.
Quick start
Check that the credentials landed, with the config tool. Before the firstconsent this reports awaiting_setup; afterwards it names the account the serveris acting as:
{ "action": "status" }
Then call a domain tool. On docs, create returns the new document's ID, whichgetText reads back:
{ "action": "create", "title": "Notes", "content": "First line." }
{ "action": "getText", "documentId": "<id-from-create>" }
time, config, and help need no Google account, so they answer even beforeconsent -- time is the quickest check that the server is wired up at all:
{ "action": "getCurrentTime" }
To act as a second Google account, see Multi-account.
Multi-account
Every domain tool takes an account parameter -- the email of the Google accountthe call acts as. Omit it and the call runs against the primary account.
{ "action": "search", "query": "is:unread", "account": "[email protected]" }
{ "action": "search", "query": "is:unread" }
Those two gmail calls read two different mailboxes: the first [email protected],the second whichever account is primary.
Accounts are managed through the config tool:
| Call | Effect |
|---|---|
config(action="account_add") |
Returns a URL to open; completing the Google consent there adds one more account. |
config(action="account_list") |
The configured accounts and which one is primary. |
config(action="account_remove", account="<email>") |
Forget one account. |
config(action="account_set_default", account="<email>") |
Make one account the primary. |
The first account authorized becomes the primary. Removing the primary promotesone of the remaining accounts; removing the last one puts the server back toawaiting setup. Naming an account that is not configured is an error that namesit -- the call is never rerouted to the primary, because a silent fallback wouldact on the wrong mailbox.
account_add works in both transports and chooses the flow itself: a temporaryloopback consent server in stdio, and a fixed /accounts/callback on the runningserver over HTTP, since a Web OAuth client's redirect URI must be registered inadvance. The HTTP link is single-use and expires in 10 minutes.
value="primary" is stdio only. Over HTTP that request would have to ride theURL through Google, where anyone who obtained it could aim your default accountat one of theirs -- so remote callers change the default withaccount_set_default instead, from inside an authenticated call.
Coming from an earlier single-account build
Credentials stored by a build from before multi-account support are one flat blobof tokens. The first run afterwards adopts that blob into the multi-account layoutunder the account's email. The email comes from the stored id_token when it ispresent -- no network needed, and that is the usual case. Otherwise the server asksGoogle's userinfo endpoint, which needs network access and a token that is stillvalid or refreshable.
If neither works, the server reports itself as awaiting setup and opens the browserOAuth flow even though the stored token may still be fine. Completing that consentworks, and nothing is discarded: the account you just authorized is stored andbecomes the primary, while the old tokens are carried across under the key(unidentified) rather than being overwritten. config(action="account_list") thenshows two entries:
{ "accounts": ["(unidentified)", "[email protected]"], "primary": "[email protected]" }
Nothing routes to (unidentified): it is never promoted to primary while a realaccount remains, and no call reaches it unless you name it explicitly. It is thereso a credential whose owner could not be determined is not silently thrown away.Remove it once the re-authorized account is working:
{ "action": "account_remove", "account": "(unidentified)" }
After a successful adoption -- the usual case -- config(action="account_list")shows exactly one account, and it is the primary.
Forms scopes and re-consent
The consent screen has requested the Google Forms scopes since before the formstool existed, so it arrived without a second trip through consent.
Accounts authorized before those scopes were added are covered too, but by adifferent route: Google accepts https://www.googleapis.com/auth/drive in place ofthe Forms scopes for every Forms method this server calls, and full drive hasbeen on the consent screen since the first release. Google never widens a token ithas already issued, so if a grant covers neither -- a user may withhold individualrestricted scopes at the consent screen -- the first forms call returns a 403(Request had insufficient authentication scopes). Re-authorize just that accountwith config(action="account_add"), signing in as the same account; the record isreplaced in place, so nothing else changes.
Documentation
Full docs at mcp.n24q02m.com/servers/better-workspace-mcp/:
- Setup -- plugin install, Docker stdio, and Docker HTTP methods
- Modes overview -- stdio (default) and HTTP (multi-user, OAuth 2.1)
- Multi-user setup -- the per-JWT-
subcredential model behind Remote (HTTP mode)
Every tool also documents itself at runtime: call help for the full reference onany of them, including the exact parameters each action takes.
Deployment
No hosted endpoint is operated for this server. The supported paths are thestdio install above and a self-hosted HTTP deployment of your own.
To self-host HTTP mode, run the compose overlay from this repository:
docker compose -f docker-compose.yml -f docker-compose.http.yml up
It builds the http image locally and publishes it on host loopback only, athttp://localhost:8087. Supply GOOGLE_OAUTH_WEB_CLIENT_ID,GOOGLE_OAUTH_WEB_CLIENT_SECRET, CREDENTIAL_SECRET, PUBLIC_URL, andMCP_RELAY_PASSWORD through your shell or an .env file (seeEnvironment). For use beyond the local machine, put your ownTLS reverse proxy on the same host in front of it and set PUBLIC_URL to thatproxy's origin.
Each release also publishes multi-arch container images to Docker Hub andGHCR; their default stage is the http server.
Contributing
See CONTRIBUTING.md.
License
Apache-2.0 © n24q02m