@mindstone/mcp-server-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.4.0 · npm: not yet published
• Auth: OAuth (host-orchestrated) (GOOGLE_CLIENT_SECRET)
• Tools: 116 (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:

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

Response (trimmed):

{
  "thread": {
    "id": "1928a...",
    "subject": "Q3 planning",
    "from": "[e-mail]"
  },
  "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

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

Variable	Description
GOOGLE_CLIENT_ID	Google OAuth client ID.
GOOGLE_CLIENT_SECRET	Google OAuth client secret.
ACCOUNTS_PATH	Path to accounts.json (host-written index of authenticated accounts).
CREDENTIALS_PATH	Directory containing per-account Google OAuth token files.

Optional environment variables

Variable	Default	Description
GOOGLE_WORKSPACE_REQUEST_TIMEOUT_MS	60000	Outbound Google API request timeout in milliseconds (max 300000 = 5 min).

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": ["<path-to-repo>/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 (116)

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

Domain	Tools	Notes
Gmail	23	Email search/thread/send/compose, drafts, labels, label filters, attachments, archive/trash/read-state helpers, settings, vacation responder, and send-as aliases/signatures.
Calendar	9	Current time, free-slot lookup, calendar/event listing, event creation, updates, responses, and deletion.
Drive	15	List/search/upload/download/copy/move/trash/untrash files, folders, permissions, revisions, shared-drive discovery, and activity queries (what changed, when, by whom).
Docs	8	Read, create, append, replace, find/replace, tab listing, and batch updates.
Sheets	14	Read/write ranges, create spreadsheets, sheet management, batch operations, find/replace, and formatting.
Slides	7	Read, create, list/get slides, batch update, thumbnails, and ID extraction.
Labels	12	Gmail label CRUD and filter rules.
Contacts	4	List, search, create, and update contacts.
Chat	3	List spaces, list messages in a space, and send text messages.
Meet	3	List conference records, list transcripts, and read transcript entries (speaker + text).
Comments	5	List/create/reply/resolve/delete Drive comments.
Account	3	List, authenticate, and remove workspace accounts.
Tasks	6	List task lists, and list/create/update/complete/delete tasks.
Forms	4	Read-only access to forms and their responses.

Shared drives

All Drive file, permission, and comment tools work on shared-drive files (the files.* and permissions.* calls pass supportsAllDrives; the Comments API addresses files by ID and defines no such flag). Listing and search default to the user's own corpus plus files shared with them, so shared-drive content the user has access to but has never opened may not surface by default. To work with shared drives explicitly:

• Discover drives: list_shared_drives returns the shared drives the account can access (id, name, creation time).
• Target one drive: pass options.driveId to list_drive_files / search_drive_files. The connector forces corpora: 'drive' whenever driveId is set (the Drive API rejects any other pairing), overriding a caller-supplied corpora.
• Search everything: pass options.corpora: 'allDrives' (no driveId) to search across My Drive and all shared drives in one query. Google recommends this only for targeted searches; prefer a specific driveId for browsing.

Known Drive API limitations for shared-drive files (not fixable in this connector):

• Files native to a shared drive have no owners[] — ownership belongs to the drive itself. Use lastModifyingUser and createdTime as proxies when attributing files.
• The Revisions API does not support shared-drive files, so list_file_revisions / download_file_revision only work for My Drive files.

Vacation responder

update_workspace_vacation_responder merges with the existing settings (the Gmail API otherwise replaces the whole resource): omitted subject/body are kept, an existing HTML body stays HTML, and a pending scheduled end is preserved when end_time is omitted. To remove a scheduled end and make the auto-reply open-ended, pass clear_end_time: true (mutually exclusive with end_time). An already-past end is never carried into a re-enable.

Security notes

• Token and account writes use temp-file plus rename, restrictive permissions, fsync, and symlink rejection.
• Token refresh can be disabled by the host so a single authority owns refresh-token rotation (GOOGLE_WORKSPACE_DISABLE_REFRESH=1).
• User-recoverable failures return host-neutral recovery guidance with action_required and next_step fields.
• The bundled callback server was removed; OAuth URLs and callback handling stay with the MCP host.
• Attachment filenames are sanitised to prevent path traversal via crafted upload_workspace_attachment filename arguments.
• <untrusted-content> envelopes cover Contacts, Calendar, Comments, Forms, Tasks, and JSON-return paths.

Licence

FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.