A Model Context Protocol server that gives Claude access to Google Workspace — Gmail, Calendar, Drive, Contacts, Sheets, Docs, Slides, Tasks, and 100+ APIs via the gws CLI.
This server powers the Google Workspace connector of DataToRAG, a hosted MCP gateway with per-user OAuth, multi-account support, and Atlassian tools alongside these — add https://datatorag.com/mcp to your MCP client and skip the setup below. Or run this server yourself, standalone or as a Claude Desktop extension.
| Service | Tools | Operations |
|---|---|---|
| Gmail | 18 | send, reply, forward, read, search, list, create draft, update draft, send draft, delete draft, mark read, list filters, create label, list labels, update label, delete label, label message, save attachment to Drive |
| Calendar | 6 | list events, get event, create, update, delete, freebusy |
| Contacts | 7 | search, get, list, create, update, delete, directory search |
| Drive | 5 | search, read file, create folder, rename, copy |
| Sheets | 14 | read, query, update, append, create, delete, add tab, rename tab, delete tab, clear, find rows, format range, format table, batch update |
| Docs | 5 | get, write, batch update, create, delete |
| Slides | 4 | get, create, batch update, delete |
| Tasks | 7 | list task lists, create task list, list tasks, create, update, complete, delete |
| Generic | 1 | gws_run — fallback for any GWS API not covered above |
| Auth | 1 | OAuth login and status |
68 tools total. All tools support shared (team) Drives.
gmail_send / gmail_reply / gmail_forward / gmail_create_draft / gmail_update_draft / gmail_send_draft — The account's Gmail signature is appended when a message is sent AND when a draft is written, so a model composing a message should not write a sign-off of its own. The signature comes from users.settings.sendAs, the isDefault entry (or the entry matching a draft's From), read fresh on every send and never cached — a client is built per tool call with that caller's token, so a remembered value would go out on someone else's mail. Gmail's API exposes only the new-email signature, so replies and forwards use it too. Pass signature: false to send without it and skip the lookup. Every response carries a signature field: applied, none_set, suppressed, already_present, unavailable or skipped_unsupported_draft. A failed lookup never blocks the send.
The signature goes in the message's HTML part only, as the stored markup unchanged — so an image signature is simply a hosted URL that passes through, and nothing can mangle it. The plain-text part is built from the body alone and never carries it. A plain body send is therefore promoted to multipart/alternative when the account has a signature, with the plain half exactly as the caller wrote it; with no signature a plain send is byte-identical to before. The accepted cost is that a text-only reader sees the message without the signature.
gmail_create_draft / gmail_update_draft — Create or replace a Gmail draft. Constructs RFC 2822 MIME messages from structured parameters (to, subject, body, cc, bcc) and base64url-encodes them. gmail_update_draft preserves threading automatically — if no thread_id is provided, it fetches the existing draft's thread ID before replacing the message. Both sign the draft exactly as the send tools sign a message (HTML part only, signature: false to leave it out, a signature field in the response). Gmail's own Compose signs when a draft is written, and a draft made here and then sent from Gmail's UI never passes through gmail_send_draft, so signing only at send time left that draft with no signature at all.
gmail_read — Full MIME payload by default. Pass text_only: true for a compact view (flattened from/to/cc/subject/date, decoded text body with HTML fallback, attachment metadata) that avoids base64 payloads overflowing the response — typically ~2% of the full size. max_body_chars truncates the body with a marker (implies text_only). When a message has no text/plain part, its HTML is flattened to text; at most 512KB of that markup is read, and a message over the limit says so in the returned body. Ordinary mail is far below it.
gmail_search / gmail_list — Results are flattened to {id, threadId, from, to, subject, date, snippet, labelIds} per message instead of the raw metadata payload.
gmail_send_draft / gmail_delete_draft — Send or permanently delete an existing draft by its draft ID. gmail_send_draft sends a reviewed draft and removes it from Drafts (no orphaned draft left behind), completing the create → review → send loop. A draft written by the draft tools already carries its signature, so it is sent unchanged and reports already_present: a draft is signed once. For a draft that does not (one written in Gmail's UI with signatures off, or with signature: false), it rewrites the stored MIME to insert the signature into the HTML part, keeping every header and the plain part untouched, and inserting above a quoted reply; a text/plain-only draft gains an HTML part the same way a plain send does. A draft it will not rewrite is sent exactly as written and reports skipped_unsupported_draft: an attachment, an inline image, a nested multipart, an encoding it cannot re-emit, a part declaring a charset other than UTF-8 or US-ASCII, or a message whose bytes are not valid UTF-8 (both would be mangled by the rewrite). Nothing in the signature path can cost you the send — a failed read, a rewrite Gmail rejects and a rewrite too large to transmit all fall through to sending the draft untouched. When the signature does not fit the encoding the HTML part declares (an emoji in a 7bit part, or an over-long line), that part is re-encoded as base64 rather than shipped as invalid MIME. gmail_delete_draft deletes immediately (does not move to Trash).
gmail_mark_read — Marks messages as read by removing the UNREAD label. Also supports adding/removing arbitrary labels (STARRED, IMPORTANT, etc.) via add_labels and remove_labels arrays. Pass message_id for a single message, or message_ids (up to 1000) to modify a batch in one API call via users.messages.batchModify. Removes UNREAD by default when no label arrays are given.
gmail_label_message: Labels many messages in one call. Pass message_ids (up to 1000) with add_labels and/or remove_labels and every message is modified by a single users.messages.batchModify request; the label-and-mark-read pair is one call (add_labels: ["<label id>"], remove_labels: ["UNREAD"]). Returns a per-message outcome (results[]: id, ok, error), and if the batch request is refused each id is retried on its own so a partial batch is visible. message_id is for a single message only.
gmail_list_filters — Reads the filters a mailbox already has, so you can see
what automation exists before adding more. Reading filters works under
gmail.modify.
Creating and deleting filters is not currently exposed. Google accepts only
gmail.settings.basic on users.settings.filters.create and .delete, and
gmail.modify does not carry it, so those calls fail with insufficient scopes
regardless of what the caller does. Rather than ship two tools that can only
fail, they are withheld until that scope is granted. Gmail filters are also
immutable, so when they return, "editing" one means create new + delete old.
gmail_save_attachment_to_drive — Fetches an attachment from Gmail and uploads it directly to Drive server-side. No base64 data flows through the conversation. Uses async file I/O with guaranteed temp file cleanup via try/finally.
calendar_list_events — Compact view by default: per event you get id, title, times, location, a plain-text description (HTML stripped, truncated at 500 chars, tune with max_description_chars), the organizer, an attendee count plus your own response status, video join links (Meet, or Zoom and friends from conference data), a recurring flag, and attachments. Meetings with 10 or fewer attendees keep their full roster, so a 1:1 still tells you who it's with; larger meetings collapse to the count. Roughly 85% smaller than the raw payload on a busy calendar. Pass full: true for the raw Calendar API response.
calendar_get_event — Full event details with the description converted to plain text. Pass full: true to keep the original HTML.
drive_search — Searches across both personal and shared Drives. Supports full Drive query syntax including folder parents, mimeType filters, and name matching.
drive_create_folder — Creates a folder in Drive, optionally inside a parent folder.
drive_rename_file — Renames a file or folder. Sends only name, so nothing else about the file changes; a blank or whitespace-only name is rejected rather than written, because Drive accepts an empty name and the file then cannot be found by name.
drive_copy_file — Copies a file and names the copy in the same call, optionally into parent_id. This is the template path: the copy carries the original's tabs, formatting and formulas, where a hand-rebuild drifts from the template. Folders cannot be copied — Drive returns 403 cannotCopyFile: "This file cannot be copied by the user", which reads like a permissions problem and is not one.
drive_read_file — Reads the text content of any file in Drive by file ID. Routes by mimeType:
- Google Docs → plain text extraction
- Google Sheets → row/column data (A1:Z1000)
- Google Slides → slide structure with placeholder maps and text
- Office formats (.docx, .xlsx, .pptx) → server-side conversion to native Google format, read converted copy, then delete temp copy (guaranteed cleanup via try/finally)
- Plain text / CSV (
text/plain,text/csv) → raw content fetch - Unsupported types (PDF, images, etc.) → returns
{ error: "Unsupported file type: <mimeType>" }
docs_get — Three modes:
text(default): plain text with[image:<id>]placeholders for inline images, best for reading/summarizingindex: text with startIndex/endIndex character positions plus inline object references, use before positional editsfull: raw API response, for debugging or style operations
All modes include the inlineObjects metadata map (contentUri, size, margins, crop, border) when images are present.
docs_create / sheets_create — Return stripped responses with only essential fields:
- docs_create →
{ documentId, title } - sheets_create →
{ spreadsheetId, title, spreadsheetUrl }
slides_get / slides_create — Return trimmed responses (no masters, layouts, geometry, styling). Each slide includes:
placeholder_map: maps standard types (TITLE, BODY, SUBTITLE) to objectIdselements: all shapes — both standard placeholders and custom text boxes- Empty placeholders are included so callers can insert text immediately after create without a redundant get call
sheets_read — Returns normalized data:
columnCountderived from the widest row (handles empty leading rows correctly)- All rows padded to uniform column count with empty strings
sheets_append — Uses direct Sheets API (spreadsheets.values.append) to preserve 2D array structure. Each inner array becomes a separate row.
docs_write — Uses batchUpdate API with insertText, correctly handles newlines, em dashes, and unicode characters.
gws_run — Fallback tool for any Google Workspace API not covered by the dedicated tools. Accepts service, resource, method, params, and JSON body. Use only when no dedicated tool exists.
Go to Google Cloud Console and create a new project (or use an existing one).
Enable each API you plan to use in your project. Click the links below and hit Enable on each page:
- Gmail API
- Google Calendar API
- Google Drive API
- Google Docs API
- Google Sheets API
- Google Slides API
- People API (for contacts)
- Tasks API
Go to OAuth consent screen:
- Select External user type
- Fill in the app name (e.g. "Google Workspace CLI") and your email
- Save and continue through all screens
- Under Test users, click Add users and add your Google account email
Go to Credentials:
- Click Create Credentials → OAuth client ID
- Application type: Desktop app
- Click Create
- Copy the Client ID and Client Secret
cp .env.example .envOpen .env and fill in your Client ID and Client Secret from the previous step.
pnpm install
pnpm run build
pnpm run build:extensionThis produces google-workspace-mcp.mcpb.
Open Claude Desktop → Settings → Extensions → Install from file → select google-workspace-mcp.mcpb.
When the extension loads for the first time, a browser window opens automatically for Google OAuth login. Sign in and authorize the app. After that, all tools are ready to use.
Note: If your app is in testing mode (unverified), you'll see a "Google hasn't verified this app" warning. Click Advanced → Go to <app name> (unsafe) to proceed. This is safe for personal use.
pnpm install
pnpm run buildWith the env vars from step 5 set, run:
./bin/gws-aarch64-apple-darwin/gws auth login -s drive,gmail,sheets,calendar,docs,slides,people,tasksnode server/index.jsThe MCP server starts on http://localhost:39147/mcp (override with PORT env var).
claude mcp add google-workspace --transport http http://localhost:39147/mcpOr add to Claude Desktop MCP config:
{
"mcpServers": {
"google-workspace": {
"type": "streamable-http",
"url": "http://localhost:39147/mcp"
}
}
}| Variable | Default | Description |
|---|---|---|
PORT |
39147 |
HTTP server port |
GWS_OAUTH_CLIENT_ID |
— | OAuth client ID |
GWS_OAUTH_CLIENT_SECRET |
— | OAuth client secret |
src/
├── create-server.ts # Shared MCP server factory (accepts optional per-session client)
├── extension.ts # Stdio entry point (.mcpb extension, auto-auth on startup)
├── index.ts # HTTP entry point (StreamableHTTP, /health + /mcp endpoints)
├── gws-client.ts # Wrapper around the gws CLI binary, DEFAULT_SERVICES constant
└── tools/
├── response.ts # Response helpers (JSON formatting, 900KB truncation)
├── auth.ts # OAuth login (browser-based, no gcloud needed)
├── gmail.ts # Gmail tools (drafts, mark read, attachments to Drive)
├── gmail-signature.ts # Signature lookup, HTML insertion, already-present check
├── gmail-draft-send.ts # Signs a draft's stored MIME (parse, insert, re-encode)
├── calendar.ts # Calendar tools
├── contacts.ts # Contacts / People API tools
├── drive.ts # Drive tools (search, read file, create folder)
├── sheets.ts # Sheets tools (normalized reads, direct API append)
├── docs.ts # Docs tools (text/index/full modes, inline image metadata)
├── slides.ts # Slides tools (trimmed responses, placeholder maps)
├── tasks.ts # Google Tasks tools (lists, CRUD, complete)
├── generic.ts # Generic gws_run fallback
└── index.ts # Tool registry (flat Map<name, handler>)
The server wraps the gws CLI binary, which handles OAuth token management and API discovery. Each tool either uses client.helper() for high-level CLI commands or client.api() for direct Google API calls.
The extension (extension.ts) runs via stdio for Claude Desktop .mcpb bundles. The HTTP server (index.ts) runs as a standalone process for Claude Code or other MCP clients. Both share the same createMcpServer() factory.
- Shared Drive support: All Drive API calls include
supportsAllDrives: true(andincludeItemsFromAllDrives: truefor list operations) so files on team Drives are accessible - Sandbox compatibility: Sets
cwd: os.tmpdir()andGOOGLE_WORKSPACE_CLI_CONFIG_DIRfor Claude Desktop's read-only filesystem - OAuth credentials: Reads from env vars, falls back to bundled
oauth.json(injected at build time byscripts/build-extension.sh) - Auto-auth: Extension checks auth status and scope coverage on startup, opens browser for OAuth login if needed (non-blocking — MCP server starts immediately)
- X-User-Token support: HTTP server accepts
X-User-Tokenheader to create per-session clients with pre-obtained access tokens (viaGOOGLE_WORKSPACE_CLI_TOKENenv var) - Response truncation: All responses capped at 900KB to stay within context limits
- Context optimization: docs_get, slides_get, and sheets_read aggressively strip metadata to minimize context usage. docs_get text mode reduces ~50KB API responses to ~2-3KB. slides_get strips masters/layouts/geometry/styling. sheets_read uses the values-only API endpoint.
- Inline image metadata: docs_get includes
inlineObjectsmap with image metadata (contentUri, size, margins) without embedding actual image bytes - Slides trimming: Strips masters, layouts, geometry, and styling from API responses — returns only objectIds, placeholder types, and text content
- Office file reading:
drive_read_filecopies Office files with explicit target mimeType to trigger server-side conversion, reads the native copy, then deletes it (guaranteed cleanup via try/finally) - Unsupported type guard:
drive_read_fileonly fetches raw content fortext/plainandtext/csv— all other non-native types return a clean error instead of binary data - Platform support: macOS (arm64, x64), Linux (x64), Windows (x64)
pnpm run dev # Watch mode — recompiles on changeMIT