Google Workspace

@mindstone/mcp-server-google-workspace

Google Workspace MCP server — Gmail, Calendar, Drive, Docs, Sheets, Slides, Contacts, Chat, Meet, Tasks, Forms, Comments, and account diagnostics.

*Multi-account Google Workspace MCP. Host-orchestrated OAuth (the connector neither runs a callback server nor mints OAuth URLs), atomic per-account credential writes, and a structured auth_required handoff so the host drives the sign-in flow rather than the server.*

Status

• Version: 0.5.5 · npm: not yet published
• Auth: OAuth (host-orchestrated) (GOOGLE_CLIENT_SECRET)
• Tools: 124 (Gmail, Calendar, Drive, Docs, Sheets, Slides, Contacts, Chat, Meet, Tasks, Forms, Comments, Account)
• Surface: cloud-api
• Machine-readable: STATUS.json

This connector is based on aaronsb/google-workspace-mcp and credited under package.json#attribution.

Why this exists

When we ported this in early 2026, Google had not published a first-party MCP server for the Workspace surface. The community options at the time each got parts of the job right — Aaron Brown's aaronsb/google-workspace-mcp, which we used as the starting point, covered the breadth of Workspace APIs but ran its own browser-callback server during OAuth, which our host application already does. We forked it so that the MCP host can own the entire OAuth flow (the connector returns a structured auth_required response instead of running a callback server or computing OAuth URLs), per-account token files are written atomically with restrictive permissions and symlink rejection, and the connector goes through our own security review before each release. Google's Workspace MCP has since shipped; we continue to maintain this one because it integrates with our host's credential-file layout, host-orchestrated OAuth handoff, and recovery-guidance contract. This is now a hard fork maintained independently in this repository — we do not sync changes from the upstream project.

Example interaction

"Find the email thread Alice sent yesterday about Q3 planning and reply with 'thanks, will read tonight'."

Tools the host calls:

1. search_workspace_emails — searches Gmail for from:alice@... subject:"Q3 planning" newer_than:1d.
2. reply_to_workspace_email — replies on the returned thread ID with the supplied body.

Response (trimmed):

{

"thread": { "id": "1928a...", "subject": "Q3 planning", "from": "alice@example.com" }, "reply": { "id": "1928b...", "labelIds": ["SENT"] } }

Requirements

• Node.js 20+ (engines.node is >=18, but the build and tests are exercised on 20 and 22)
• npm
• A host application that performs the Google OAuth flow and writes accounts.json plus per-account token files for the connector to read.

Quick Start

Install & build

cd <path-to-repo>/connectors/google-workspace

npm install npm run build

npx (once published)

npx -y @mindstone/mcp-server-google-workspace

Local

node dist/index.js

Configuration

When Google says "slow down". There is nothing to configure here. For reads (GET, HEAD and OPTIONS), short-window rate limits wait and retry the request; the total can be longer than a minute and a half when Google sends Retry-After, and each wait is capped at 64 seconds. Requests that already succeeded are not sent again. POST and PATCH are never replayed by the retry policy; PUT and DELETE keep the ordinary 429 retries but do not retry rate-limit 403s. Non-rate-limit permission errors and longer-window 403 quota responses keep their ordinary behavior; 429 responses give back-off advice, and some tools also include Google's error text. When the read retry loop ends, the error says so (recoveryExhausted: true); a host that retries failed calls itself can read that field and skip its own retry.

Values you pass back stay exact. Results mark text that comes from outside (email bodies, file names, event titles) as untrusted content, by wrapping it in an tag. Values meant to be passed back into another call are returned exactly as Google sent them: page tokens (which fetch the next page of results) and the IDs of messages, threads, files, events, calendars, Chat spaces and Meet records. You can pass them straight into the next call.

This server is designed to run alongside a host application that performs the Google OAuth flow on its own. The host writes credentials to disk; this server reads them.

Required environment variables

Optional environment variables

GOOGLE_WORKSPACE_DISABLE_REFRESH=1 may be injected by a host to make the connector return auth_required instead of refreshing tokens. It is intentionally not a user-facing setup variable.

Authentication flow

authenticate_workspace_account returns a structured auth_required response:

{

"status": "auth_required", "user_action": { "id": "google.connect_account" }, "agent_action": { "instruction": "Connect Google Workspace to continue. The user will be redirected to Google's sign-in." }, "setupToolName": "authenticate_workspace_account" }

The connector does not run a callback server and does not generate OAuth URLs. The MCP host computes the Google OAuth URL and handles the callback. Once the host has written the account's token file under CREDENTIALS_PATH/ and an entry into ACCOUNTS_PATH, the next tool call succeeds.

Host configuration examples

Claude Desktop / Cursor

{

"mcpServers": { "GoogleWorkspace": { "command": "npx", "args": ["-y", "@mindstone/mcp-server-google-workspace"], "env": { "GOOGLE_CLIENT_ID": "your-google-oauth-client-id", "GOOGLE_CLIENT_SECRET": "your-google-oauth-client-secret", "ACCOUNTS_PATH": "/absolute/path/to/accounts.json", "CREDENTIALS_PATH": "/absolute/path/to/credentials" } } } }

Until the host has written ${ACCOUNTS_PATH} and the matching per-account token file under ${CREDENTIALS_PATH}/, every tool call returns the structured auth_required response (see the Authentication flow above).

Local development (no npm publish needed)

{

"mcpServers": { "GoogleWorkspace": { "command": "node", "args": [" /connectors/google-workspace/dist/index.js"], "env": { "GOOGLE_CLIENT_ID": "your-google-oauth-client-id", "GOOGLE_CLIENT_SECRET": "your-google-oauth-client-secret", "ACCOUNTS_PATH": "/absolute/path/to/accounts.json", "CREDENTIALS_PATH": "/absolute/path/to/credentials" } } } }

Tools (124)

The full list lives under src/tools/definitions/ and is also surfaced in tools-inventory.json. Grouped by domain:

Compose send status

In hosts that remember send status, sending an email closes its other compose copies. Reloaded cards show "Email sent" with the send time and hide Reopen because they do not have the sent contents. The copy used to send keeps its posted contents in a read-only sent view, including when confirmation follows a lost reply. After an error or block reply, a later sent status from another copy shows only the sent bar, without this copy's contents. While a send is in progress, other copies show “Sending…” with Send, Retry, Cancel and Save draft (where available) disabled. Replies to this copy’s own requests keep those controls locked until the other send ends. If the send ends without a confirmed outcome, those copies return to editing and keep any earlier uncertainty. A copy waiting for its own Send reply keeps its sending view. Sent views stay read-only, and uncertainty remains until a send is confirmed. After an error or missing confirmation, check whether the email was sent before using Retry; the notice stays visible while editing and returns on Reopen. Collapsing the card does not resolve that uncertainty. Policy-block explanations stay visible while editing with Send disabled. Cancel says "Nothing sent" only when no send may have gone through, including a not-dispatched failure before the request left the device.

When sending is blocked by your settings, your organization or security policy, the card hides Retry and keeps Cancel. If the server is stopped, Retry remains available.

Send requests declare _meta: { 'mcp-app/cardOutcome': 'sent' } to supporting hosts. When your own setting blocks sending, Retry stays unavailable; the Gmail fallback depends on the structured user-disabled reason. Draft saves do not declare a send outcome; Cancel after a draft-save timeout says "Nothing sent" unless an earlier send remains uncertain.

Sheets read limits

read_workspace_spreadsheet_values accepts max_rows and max_cols to keep the first rows and columns of a values read, including value_view: "shaped" and return_json: true. They refer to sheet rows and columns even with major_dimension: "COLUMNS". Omitted limits leave that dimension unchanged. A truncated result reports truncated: true in JSON or a truncation notice in text.

Anchor envelopes keep their first/last windows, summary and continuation token unchanged. Limits apply when reading a continuation page, but truncation creates no new token and does not advance the original token. To retrieve omitted cells, re-read a