HUB
Sign inSign up

n24q02m/workspace

By n24q02m

•Updated 2 days ago

Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Chat/People + multi-accou

Image
0

1.9K

n24q02m/workspace repository overview

⁠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.

Mode: stdio · http remote oauth CI CD codecov Latest release semantic-release License: Apache-2.0

Docs⁠ · Install⁠ · Quick start⁠ · Community⁠

Sister projects from n24q02m (click to expand)
ProjectTaglineTag
better-semantic-release⁠Drop-in python-semantic-release fork with built-in release-safety guards (orp...Tooling
claude-plugins⁠Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea...Marketplace
crg⁠Knowledge graph for token-efficient code reviews -- semantic search and call-...MCP
email⁠IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att...MCP
fastretrieval⁠Fast multi-model retrieval runtime: ONNX and GGUF embeddings, reranking, and ...Tooling
hull⁠hull is the shared monorepo core for the wet, crg and mnemo self-hosted stackMCP
jules-task-archiver⁠Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a...Tooling
mnemo⁠Persistent AI memory with hybrid search. Open, free, unlimited.MCP
notion⁠Markdown-first Notion for AI agents -- pages, databases, blocks, and comments...MCP
sillstone⁠Pure-Rust multimedia, hashing, and array suiteTooling
skret⁠Secrets without the server.CLI
tacet⁠A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl...Tooling
telegram⁠Telegram for AI agents -- messages, chats, media, and contacts across both bo...MCP
tools-docs⁠Docs portal for the n24q02m open-source tool stack (skret, MCP plugins, hull,...Tooling
wet⁠Open-source MCP server for AI agents: web search, content extraction, and lib...MCP
workspace⁠Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...MCP

⁠Table of contents

⁠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": "<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 is now io.github.n24q02m/workspace; the entry published under io.github.n24q02m/better-workspace-mcp stays on the registry as a frozen historical release, 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 ~/.workspace/ (a store an earlier release wrote under ~/.better-workspace/ is copied forward on the next start, and the older ~/.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:

⁠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 <namespace>.

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 stdio transport directly, with no HTTP hop inside it.

ModeSelected byServesGoogle OAuth client
stdiothe defaultone user, on their own machineDesktop app
http--http, MCP_TRANSPORT=http, or TRANSPORT_MODE=httpseveral users, one credential bucket per user namespaceWeb application
⁠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
VariableRequiredWhat it does
GOOGLE_OAUTH_CLIENT_IDyesWeb client id. The server refuses to start without it.
GOOGLE_OAUTH_CLIENT_SECRETyesWeb client secret. Same.
CREDENTIAL_SECRETyesDerives the encryption key of each user's credential store. The server refuses to start without it, rather than fail in the middle of a user's consent.
WORKSPACE_USERS_FILEyes in HTTPUsers file that maps each bearer token to a user namespace (hull multi auth). Unset uses hull's default location.
WORKSPACE_DATA_DIRnoBase directory for the credential store (<dir>/.workspace/, one encrypted blob per user). Unset uses the home directory. A relative value is resolved under the home directory and must stay inside it, so use an absolute path for a mounted volume.
PORTnoListen port. 0 (the default) asks the OS for a free one.
HOSTnoBind address. Defaults to loopback, so a container needs 0.0.0.0.

Credentials are stored on local disk under ~/.workspace/, which is the data volume in the container. A store from an earlier release (~/.better-workspace/) is copied forward on startup, and the older ~/.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:

ToolWhat it covers
docsGoogle Docs -- getText, create, writeText, getSuggestions, replaceText, formatText
driveFiles and folders -- search, findFolder, createFolder, moveFile, renameFile, trashFile, downloadFile, getComments
calendarEvents -- listCalendars, listEvents, getEvent, createEvent, updateEvent, deleteEvent, respondToEvent, findFreeTime
gmailMail -- search, get, send, createDraft, sendDraft, modify, batchModify, modifyThread, downloadAttachment, listLabels, createLabel
sheetsSpreadsheets, read-only -- getText, getRange, getMetadata
slidesPresentations -- 19 actions covering slides, text, shapes, images, tables, and speaker notes
tasksTask lists and tasks -- listTaskLists, listTasks, createTask, updateTask, completeTask, deleteTask
chatGoogle Chat -- listSpaces, findSpaceByName, setUpSpace, getMessages, listThreads, sendMessage, sendDm, findDmByEmail
peopleProfile lookups -- getMe, getUserProfile, getUserRelations
formsForms -- create, get, batchUpdate, listResponses, getResponse
timeLocal date/time/timezone helpers (no Google account needed)
configCredential state and account management (CLI: config-tool)
helpFull 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 or deleting forms goes through drive.

⁠Response size

A Google read can return megabytes from one call, so every action whose payload can grow is bounded by default:

  • 20,000 characters per response. Raise it with max_chars (1--100,000), or pass full: true for the complete payload. The same envelope docs exposes as limit/preview and sheets as max_chars/full.
  • Listings that page keep their page size (default 20, clamped to 1--100) and always return their nextPageToken; listings with no cursor (getImages, findFolder, findSpaceByName, listCalendars, getUserRelations, free/busy slots, labels) also cap how many items one response carries (50--100).
  • Truncation is never silent. A cut payload carries _truncation: {truncated, total_characters, returned_characters, omitted_items?, note} whose note reads [Content truncated: showing <kept> of <total> characters (<omitted> omitted). ...]. A JSON payload stays parseable, and a pagination cursor is never cut.
workspace gmail get --messageId <id> --max_chars 60000 --json   # a longer body
workspace slides getText --presentationId <id> --full --json     # the whole deck

⁠CLI

Every tool is also a shell subcommand, so the same operations work without an MCP client. workspace <tool> <action> turns those parameters into the tool's input object and calls the same handler the server registers -- one dispatch, two front doors, so credential gating and validation behave identically.

workspace <tool> <action> [--param <value>]... [--json]

--json prints one envelope on stdout -- {"tool", "action", "result"}, where result is the tool's own payload (parsed when the tool emits JSON, the raw text otherwise). Without it you get the tool's text as-is. A tool failure prints to stderr and exits 1; argv the CLI cannot parse exits 2. workspace --help lists the tool subcommands and the operator commands (auth, config, status, logout, doctor, token) separately, and workspace <tool> --help prints that tool's actions and options.

One tool name is already taken. config is the operator command that reads the credential store hull manages (workspace config status); the MCP config tool is a different surface -- credential lifecycle plus the Google accounts the server acts as. It keeps a console path under the alias config-tool, so neither command can silently stand in for the other:

workspace config-tool status --json
workspace config-tool account_list
GroupExample
docsworkspace docs getText --documentId <document-id> --limit 2000
driveworkspace drive search --query "name contains 'Q3 report'" --pageSize 5
calendarworkspace calendar listCalendars --json
chatworkspace chat listSpaces --json
gmailworkspace gmail search --query "is:unread" --maxResults 5 --json
sheetsworkspace sheets getRange --spreadsheetId <spreadsheet-id> --range "Sheet1!A1:C10"
slidesworkspace slides getMetadata --presentationId <presentation-id>
tasksworkspace tasks listTasks --taskListId <task-list-id> --maxResults 20
peopleworkspace people getMe --json
formsworkspace forms listResponses --formId <form-id> --pageSize 10
timeworkspace time getCurrentTime --json
config-toolworkspace config-tool status --json (the MCP config tool)
helpworkspace help gmail

Values are coerced from the tool's own schema: --maxResults 5 is a number, --includeSpamTrash (also --includeSpamTrash true, or --no-includeSpamTrash) is a boolean, and --labelIds INBOX,IMPORTANT (or a JSON array) is a list. Every domain accepts --account <email> to choose the Google account, exactly like the tool's account parameter.

⁠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" }

From a shell the same call is workspace config-tool status --json, and it works before consent -- it reads the store, it does not need Google.

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": "<id-from-create>" }

time, config, and help need no Google account, so they answer even before consent -- 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 account the 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:

CallEffect
config(action="account_add")In stdio, returns a URL to open; completing the Google consent there adds one more account. Over HTTP it returns the workspace auth --user <namespace> command to run on the host.
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.

From a shell, the same four calls:

workspace config-tool account_add
workspace config-tool account_list
workspace config-tool account_remove --account <email>
workspace config-tool account_set_default --account <email>

config-tool, not config: the plain name is the operator command that reads the credential store.

The first account authorized becomes the primary. Removing the primary promotes one of the remaining accounts; removing the last one puts the server back to awaiting setup. Naming an account that is not configured is an error that names it -- the call is never rerouted to the primary, because a silent fallback would act on the wrong mailbox.

account_add chooses its flow by transport. In stdio it starts a temporary loopback consent server and returns the URL. Over HTTP it does not serve consent; it returns the workspace auth --user <namespace> command for the host.

value="primary" is stdio only; remote callers change the default with account_set_default.

⁠Coming from an earlier single-account build

Credentials stored by a build from before multi-account support are one flat blob of tokens. The first run afterwards adopts that blob into the multi-account layout under the account's email. The email comes from the stored id_token when it is present -- no network needed, and that is the usual case. Otherwise the server asks Google's userinfo endpoint, which needs network access and a token that is still valid or refreshable.

If neither works, the server reports itself as awaiting setup and opens the browser OAuth flow even though the stored token may still be fine. Completing that consent works, and nothing is discarded: the account you just authorized is stored and becomes the primary, while the old tokens are carried across under the key (unidentified) rather than being overwritten. config(action="account_list") then shows two entries:

{ "accounts": ["(unidentified)", "[email protected]"], "primary": "[email protected]" }

Nothing routes to (unidentified): it is never promoted to primary while a real account remains, and no call reaches it unless you name it explicitly. It is there so 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.

The consent screen has requested the Google Forms scopes since before the forms tool existed, so it arrived without a second trip through consent.

Accounts authorized before those scopes were added are covered too, but by a different route: Google accepts https://www.googleapis.com/auth/drive in place of the Forms scopes for every Forms method this server calls, and full drive has been on the consent screen since the first release. Google never widens a token it has already issued, so if a grant covers neither -- a user may withhold individual restricted scopes at the consent screen -- the first forms call returns a 403 (Request had insufficient authentication scopes). Re-authorize just that account with config(action="account_add"), signing in as the same account; the record is replaced in place, so nothing else changes.

⁠Documentation

Full docs at docs.n24q02m.com/servers/workspace/⁠:

  • Setup⁠ -- plugin install, Docker stdio, and Docker HTTP methods

Every tool also documents itself at runtime: call help for the full reference on any of them, including the exact parameters each action takes.

⁠Deployment

No hosted endpoint is operated for this server. The supported paths are the stdio 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, at GOOGLE_OAUTH_WEB_CLIENT_ID, GOOGLE_OAUTH_WEB_CLIENT_SECRET, CREDENTIAL_SECRET, and WORKSPACE_USERS_FILE through your shell or an .env file (see Environment⁠). The users file maps each bearer token to a user namespace; accounts are added on the host with workspace auth --user <namespace>. For use beyond the local machine, put your own TLS reverse proxy on the same host in front of it.

Each release also publishes multi-arch container images to Docker Hub and GHCR; their default stage is the http server.

⁠Contributing

See CONTRIBUTING.md⁠.

⁠License

Apache-2.0⁠ © n24q02m

Tag summary

Content type

Image

Digest

sha256:d942d7b42…

Size

172.3 MB

Last updated

2 days ago

docker pull n24q02m/workspace