google-tools-mcp

The easiest way to connect your AI agent to Google Workspace.

160 tools for Drive, Docs, Sheets, Gmail, Calendar, Forms, Slides, Tasks, and Maps — all in one package. One install, one auth, and you're done.

npx -y google-tools-mcp setup

Why google-tools-mcp?

One command to install. No cloning repos, no building from source, no Docker. Just npx -y google-tools-mcp setup and it works.
One login for everything. A single OAuth flow gives you Drive, Docs, Sheets, Gmail, Calendar, Forms, Slides, and Tasks. No juggling multiple tokens or servers.
Auth that stays out of your way. No browser popup until your first tool call. After that, your token is saved and you won't be asked again.
Read anything in your Drive. PDFs, Word docs (.docx), spreadsheets — your AI agent can read them directly. No extra setup.
160 tools, zero config. Every tool is available the moment the server starts. Send emails, create Docs and Slides, manage Tasks and calendar events, build forms, search places — it's all there.
Switch between Google accounts. Set a profile name and keep work and personal accounts completely separate.
No telemetry. No tracking. Fully open source.

Quick Start

You can be up and running in under 5 minutes.

Guided Setup (recommended)

Run the setup wizard — it opens the right Google Cloud Console pages for you and saves your credentials automatically:

npx -y google-tools-mcp setup

The wizard walks you through:

Enabling all required Google APIs (opens in your browser)
Configuring the OAuth consent screen
Creating OAuth credentials
Authenticating with Google

The setup wizard can add the MCP server to Codex or Claude Code automatically when their CLIs are installed. You can also add it manually later (see Step 3 below).

Manual Setup

Click to expand manual setup instructions

Step 1: Create Google OAuth Credentials

Go to the Google Cloud Console
Create a project (or use an existing one)
Enable the Google Docs API, Google Sheets API, Google Drive API, Gmail API, Google Calendar API, Google Forms API, Google Slides API, and Google Tasks API
Go to OAuth consent screen and configure it (External is fine for personal use). If your app's publishing status is Testing (the default), you must add your Google account as a test user — go to OAuth consent screen → Test users → Add users and enter your email. Without this, Google will block the OAuth flow with an "Access denied" or "app not verified" error.
Go to Credentials → Create Credentials → OAuth Client ID
Select Desktop application as the application type
Download the credentials or note your Client ID and Client Secret

Step 2: Provide Your Credentials

Choose one of the following methods (whichever you prefer):

Option A: Use `credentials.json`

Download the JSON file from Google Cloud Console and place it in either location:

~/.config/google-tools-mcp/credentials.json   (recommended — shared across projects)
./credentials.json                              (local to your project)

That's it — no env vars needed. The server will find it automatically.

Option B: Create a `.env` file

Create a .env file in either location:

~/.config/google-tools-mcp/.env   (recommended — shared across projects)
./.env                             (local to your project)

With the following contents:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_MCP_OAUTH_PORT=37547  # optional: fixed localhost callback port for remote OAuth

Option C: Set env vars in your MCP config

Add the credentials directly to your MCP configuration:

{
  "mcpServers": {
    "google": {
      "command": "google-tools-mcp",
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

(Requires npm install -g google-tools-mcp first: see Step 3 and the Troubleshooting section for why npx isn't used here.)

Credential lookup order: env vars → ~/.config/google-tools-mcp/.env → project root .env → ~/.config/google-tools-mcp/credentials.json → project root credentials.json

Step 3: Add to Your MCP Client

Local unpublished checkout

To call a local tool directly without publishing or using MCP transport, use local:tool. This loads the unpublished checkout, registers the real tools in memory, validates the arguments, and calls the tool's execute function:

npm run local:tool -- list
npm run local:tool -- help
npm run local:tool -- readDocument documentId=... format=markdown

For larger arguments, put JSON in a file and pass it with @:

npm run local:tool -- replaceDocumentWithMarkdown @args.json

Why npm install -g instead of npx? The guided setup wizard installs the package globally and points your MCP client straight at it, instead of using npx -y google-tools-mcp. npx re-resolves the whole dependency tree on every single launch, which can take 30+ seconds on some machines. That's long enough to lose the race against Claude Code's fixed 30s stdio MCP connection timeout. See Troubleshooting below if you're setting this up by hand.

First, install once:

npm install -g google-tools-mcp

Codex

Codex pins stdio servers to the legacy MCP lifecycle unless told otherwise, so its registration needs CODEX_MCP_PROTOCOL_VERSION=2026-07-28 in the env block (see Breaking change in 3.0.0). The setup wizard writes it for you; by hand, pass it with --env:

codex mcp add google \
  --env CODEX_MCP_PROTOCOL_VERSION=2026-07-28 \
  -- google-tools-mcp

With env vars (Option C):

codex mcp add google \
  --env CODEX_MCP_PROTOCOL_VERSION=2026-07-28 \
  --env GOOGLE_CLIENT_ID=your-client-id \
  --env GOOGLE_CLIENT_SECRET=your-client-secret \
  -- google-tools-mcp

Claude Code

User-scope (available in all projects):

claude mcp add -s user google -- google-tools-mcp

Project-scope (available only in the current project):

claude mcp add google -- google-tools-mcp

With env vars (Option C):

# User-scope
claude mcp add -s user google \
  -e GOOGLE_CLIENT_ID=your-client-id \
  -e GOOGLE_CLIENT_SECRET=your-client-secret \
  -- google-tools-mcp

# Project-scope
claude mcp add google \
  -e GOOGLE_CLIENT_ID=your-client-id \
  -e GOOGLE_CLIENT_SECRET=your-client-secret \
  -- google-tools-mcp

Project-Local Installation (with profile)

Via the claude CLI:

claude mcp add -s user google \
  -e GOOGLE_MCP_PROFILE=myprofile \
  -- google-tools-mcp

Or manually in your .mcp.json:

{
  "mcpServers": {
    "google": {
      "command": "google-tools-mcp",
      "env": {
        "GOOGLE_MCP_PROFILE": "myprofile"
      }
    }
  }
}

Other MCP clients

Add this to your MCP configuration (e.g., .mcp.json, claude_desktop_config.json):

{
  "mcpServers": {
    "google": {
      "command": "google-tools-mcp"
    }
  }
}

If using Option C, add an "env" block with your GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.

Prefer npx anyway, or can't install globally?

Every example above works with npx -y google-tools-mcp in place of google-tools-mcp (e.g. codex mcp add google -- npx -y google-tools-mcp). It requires no global install, but pays npx's dependency-resolution cost on every launch: see Troubleshooting for what that costs you.

Step 4: Authenticate

On your first tool call, the server will automatically open your browser for Google OAuth consent. Sign in and grant access — the token is saved to ~/.config/google-tools-mcp/token.json for future use.

Remote MCP host / local browser: Set GOOGLE_MCP_OAUTH_PORT to a fixed loopback port and create a persistent SSH local forward from the browser machine. See Remote OAuth with a persistent SSH tunnel.

You can also run the auth flow manually anytime:

npx google-tools-mcp auth

Multi-Account Support

Set the GOOGLE_MCP_PROFILE env var to use separate tokens per profile:

{
  "env": {
    "GOOGLE_MCP_PROFILE": "work"
  }
}

This stores tokens in ~/.config/google-tools-mcp/work/ instead of the default directory.

Troubleshooting

The `google` MCP server won't connect / "connection timed out"

Symptom: Claude Code (or another MCP client) reports that the google server failed to connect, timed out, or keeps disconnecting, with no other visible error. It may work sometimes and fail other times on the same machine.

Cause: If your MCP config launches the server with npx -y google-tools-mcp, npx re-resolves and verifies the entire dependency tree on every single launch, not just the first. On some machines, especially Windows (likely antivirus real-time scanning of npm's file I/O during install/verify), this reliably takes 30-34 seconds, even when the exact version is already cached locally. Claude Code's stdio MCP connection timeout is a fixed 30 seconds, so npx-launched servers are right on the failure line and frequently lose the race.

Launching directly (node dist/index.js, or the global-install path below) is faster, but it is not a guarantee. Measured on one affected Windows machine on 2026-07-24, three runs each: npx took 23.0s, 25.3s and 24.6s, a direct node launch took 14.7s, 26.0s and 12.2s. So skipping npx is worth roughly 7 seconds on average and removes a large source of variance, but on a machine with slow disk I/O a direct launch can still come close to the limit. If it still times out after you switch, what is left is the cost of reading this package's dependency tree off disk, tracked in issue #71. Full writeup in issue #46, and see docs/startup-performance.md for the per-import breakdown and how to measure any of this on your own machine.

Where to look: MCP clients that log per-server connection attempts will show the exact timing. For Claude Code, per-server logs live at:

Windows: %LOCALAPPDATA%\claude-cli-nodejs\Cache\<project-slug>\mcp-logs-google\*.jsonl
macOS: ~/Library/Caches/claude-cli-nodejs/<project-slug>/mcp-logs-google/*.jsonl: the claude-cli-nodejs cache root and per-server log folder are corroborated by an independent user report (anthropics/claude-code#18869), though not confirmed with this exact server name
Linux: ~/.cache/claude-cli-nodejs/<project-slug>/mcp-logs-google/*.jsonl (same convention as macOS, under the XDG cache dir, and unconfirmed; if it's not there, check wherever claude doctor / your Claude Code version reports its cache directory)

Look for lines like "Connection timeout triggered after ...ms" or "Successfully connected ... in ...ms". Claude Code captures the pre-handshake category line, such as Loaded all 12 categories in 1123ms., which measures server startup before the connection completes. The later ready line remains useful when you run the server directly. If startup is fast but the client still reports a near-30000ms connection time, the delay is before the server process starts, commonly in npx.

For per-tool failures, see the diagnostics runbook. It documents the redacted JSONL records written by default and how troubleshoot summarizes them.

Fix: Install the package globally and point your MCP client directly at it instead of using npx:

npm install -g google-tools-mcp

Then use google-tools-mcp (no npx) as the MCP command: see Step 3 for exact commands per client. Running npx -y google-tools-mcp setup does this for you automatically: the guided setup wizard installs the package globally and points the MCP entry straight at it. If the global install isn't possible on your machine (e.g. no write access to the global npm directory), it falls back to npx, but only if npx is actually on PATH, since a machine that can't reach npm usually can't reach npx either. If npx isn't there either, it falls back to launching whichever copy of the package is running the wizard right now. If none of the three works, it stops, explains why, and writes nothing to your MCP config rather than leaving you with a command that can't run.

Updates stop arriving after switching off `npx`

Cause: npx -y google-tools-mcp re-resolves to whatever is currently published on every launch, so it auto-updates by accident. The global-install path above trades that away for startup speed: your MCP client launches a fixed node <path> command that points at whatever was installed the moment you ran setup, and nothing else ever runs npm install -g again on its own. Left alone, a global-install user keeps running that same version forever, missing every release after it.

Fix: Update it yourself whenever you like:

npm install -g google-tools-mcp@latest

(or just re-run npx -y google-tools-mcp setup, which does the same install and re-points your MCP config). The server also helps you notice: on startup, after the MCP connection is already established, it makes a strictly time-boxed (2s), non-blocking, at-most-once-per-24-hours check against the npm registry for the latest published version, and logs a one-line warning if you're behind. This check runs after the connection handshake and is never awaited, so a slow or unreachable network can't delay or reintroduce the npx startup-timeout race this section is about; worst case, it just never gets to print the notice.

Development / Contributing

Contributor-facing deep dives live in docs/, indexed there. The rules a change has to follow (read-before-write guard, seeding after create/copy, working copies, the error boundary, how to read a test run, changelog and version) are in CONTRIBUTING.md.

dist/ is the hand-edited source for this repository. It contains plain JavaScript; there is no TypeScript, bundler, or build step.

A few files under dist/ still carry a leftover header comment naming a src/*.ts path (for example, dist/types.js starts with // src/types.ts) from before this repo was forked. No such source file exists here; treat the comment as stale and edit the .js file directly.

Run the server directly from a clone:

npm install
npm start
# Equivalent: node dist/index.js

To make an MCP client run the clone instead of the published package, use an absolute path in its configuration. Pin command to the absolute Node executable too, not a bare node: desktop and GUI MCP clients often launch with a minimal PATH that doesn't include node (this is especially common with nvm, volta, or fnm), even when node resolves fine in your own shell. Confirming node works in a terminal doesn't prove what the GUI client's process can resolve, since it may not inherit your shell's PATH at all, so hand it the resolved path directly. Get that path with:

node -p "process.execPath"

Then use that output as command:

{
  "mcpServers": {
    "google": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/google-tools-mcp/dist/index.js"]
    }
  }
}

On Windows, write both paths with forward slashes (C:/Users/you/google-tools-mcp/dist/index.js) or escape backslashes (C:\\Users\\...) — a bare C:\Users\... is invalid JSON.

Alternatively, link the clone into npm's global executable directory, then configure the client with "command": "google-tools-mcp". This has the same bare-command risk described above: a GUI client's PATH doesn't have to match your shell's, so after linking, resolve the absolute path once with command -v google-tools-mcp (macOS/Linux) or where google-tools-mcp (Windows) and put that path in command instead of the bare name.

cd /absolute/path/to/google-tools-mcp
npm install
npm link

Watch for source/runtime drift: editing a clone has no effect while the MCP client still launches npx google-tools-mcp or a separately installed global copy. Check the client's configured command and arguments, then use command -v google-tools-mcp (macOS/Linux) or where google-tools-mcp (Windows) to see which executable is selected. Restart the MCP client after changing its configuration or relinking.

Tool Categories

`files` (27 tools)

Google Drive file management and content reading.

listDriveFiles, searchDocuments, getFileInfo, getFilePath, createFolder, listFolderContents, getFolderInfo, moveFile, copyFile, renameFile, deleteFile, createDocument, createDocumentFromTemplate, listSharedDrives, listSharedWithMe, downloadFile, uploadFile, listPermissions, addPermission, removePermission, updatePermission, listRevisions, getRevision, updateRevision, readFile, searchFileContents, readDriveFile

`documents` (26 tools)

Google Docs read/write/format with markdown support.

readDocument, appendText, deleteRange, modifyText, batchModifyText, findAndReplace, insertTable, insertTableWithData, insertPageBreak, insertImage, listTabs, addTab, renameTab, listHeadings, applyParagraphStyle, getFormatting, addComment, deleteComment, getComment, listComments, replyToComment, resolveComment, updateComment, appendMarkdown, replaceDocumentWithMarkdown, replaceRangeWithMarkdown

`spreadsheets` (30 tools)

Google Sheets operations.

readSpreadsheet, writeSpreadsheet, batchWrite, appendRows, clearRange, createSpreadsheet, getSpreadsheetInfo, addSheet, deleteSheet, duplicateSheet, renameSheet, formatCells, readCellFormat, autoResizeColumns, freezeRowsAndColumns, setColumnWidths, addConditionalFormatting, copyFormatting, setDropdownValidation, createTable, deleteTable, getTable, listTables, appendTableRows, updateTableRange, insertChart, deleteChart, groupRows, ungroupAllRows, deleteColumns

`email` (16 tools)

Gmail messages and drafts (hot-path tools stay granular).

sendMessage, replyMessage, forwardMessage, getMessage, listMessages, modifyMessage, deleteMessage, trashMessage, batchGetMessages, getAttachment, createDraft, updateDraft, deleteDraft, getDraft, listDrafts, sendDraft

`email_threads` (6 tools)

Gmail thread-level operations.

getThread, listThreads, batchGetThreads, modifyThread, deleteThread, trashThread

`email_labels` (1 tool)

Gmail label management, consolidated into one dispatch tool.

manageLabel (action: create | patch | delete | get | list)

`email_settings` (6 tools)

Gmail admin and configuration, consolidated into dispatch tools.

`calendar` (8 tools)

Google Calendar — events, availability, and calendar management.

listCalendars, getEvents, manageEvent, getBusy, getFree, moveEvent, listRecurringEventInstances, manageCalendar

Backward compatibility: every former snake_case tool name (get_imap, list_messages, manage_event, …) is still available as a deprecated alias that forwards to its new implementation, but they are opt-in, not loaded by default — registering them by default would grow the tool surface these issues exist to shrink. Set GOOGLE_MCP_ENABLE_LEGACY_ALIASES=true to register them. See Gmail tool migration.

`forms` (6 tools)

Google Forms — create/read forms, manage responses, and publish settings.

create_form, get_form, batch_update_form, get_form_response, list_form_responses, set_publish_settings

`slides` (16 tools)

Google Slides presentation creation and editing.

createPresentation, updatePresentation, getPresentation, formatSlidesText, formatSlidesParagraph, styleSlidesShape, setSlidesBackground, createSlidesTextBox, createSlidesShape, getSpeakerNotes, updateSpeakerNotes, deleteSlide, duplicateSlide, reorderSlides, replaceAllTextInSlides, exportSlideThumbnail

`tasks` (8 tools)

Google Tasks task-list and task management.

listTaskLists, createTaskList, deleteTaskList, listTasks, createTask, updateTask, completeTask, deleteTask

`maps` (6 tools)

Google Maps and Places tools for geocoding, reverse geocoding, nearby and text search, place details, and directions.

mapsGeocode, mapsReverseGeocode, mapsSearchNearby, mapsSearchPlaces, mapsPlaceDetails, mapsDirections

These tools require GOOGLE_MAPS_API_KEY, a Google Maps Platform API key, separate from the Google OAuth credentials used everywhere else and not covered by the setup wizard or by Step 1 above. To get one: enable the Geocoding API, Places API (New), and Routes API for your Google Cloud project, then go to Credentials → Create Credentials → API key, and set it as GOOGLE_MAPS_API_KEY. Without it, the maps tools are still listed, but calling any of them fails with a clear error telling you to set the key.

The categories above contain 156 service-specific tools. Four general utilities — help, logout, troubleshoot, and feedback — bring the default server surface to 160 tools. See Common Workflows for practical examples.

help with no arguments returns this whole manual. help with tool: "<name>" returns just that tool's description and the JSON Schema for its arguments, exactly as tools/list publishes it, and help with listTools: true returns the registered tool names one per line. Reach for the per-tool form first: it is a few thousand characters instead of forty thousand, and it states the argument shape the tool actually takes.

Finding Character Indices in a Doc

Every index-addressed Docs tool (modifyText, batchModifyText, replaceRangeWithMarkdown, deleteRange, insertTable, insertTableWithData, insertPageBreak) needs startIndex/endIndex values. Get them with readDocument and format='index':

{"format":"index","documentId":"…","revisionId":"…","tabId":null,"documentEnd":151,
 "fromIndex":0,"totalElementCount":4,"elementCount":4,"truncated":false,
 "elements":[
   {"start":1,"end":12,"tabId":null,"type":"heading","level":1,"nesting":null,"preview":"To Do List"},
   {"start":12,"end":25,"tabId":null,"type":"listItem","ordered":true,"nesting":0,"preview":"Follow up now"},
   {"start":25,"end":80,"tabId":null,"type":"table","rows":2,"columns":2,
    "cells":[{"start":42,"end":50,"row":0,"col":0,"preview":"Name"}]},
   {"start":80,"end":81,"tabId":null,"type":"horizontalRule","nesting":null,"preview":""}]}

type is one of heading, listItem, paragraph, table, sectionBreak, tableOfContents, horizontalRule, pageBreak, or inlineObject — a paragraph is exactly one of them, never two. An inlineObject is further promoted to a more specific type when the underlying element is one of footnoteReference, columnBreak, equation, richLink, person, or autoText. Ranges are the raw Docs indices, 1-based and end-exclusive, so they can be handed straight to a mutating tool. Top-level ranges never overlap; the one nesting is table cells, which carry their own indices inside their table's cells array.

documentEnd is the one field that is not a usable endIndex. It is one past the last addressable index, because the Docs body always ends with a final newline that no range may cover. To address everything from index N to the end of the body, pass endIndex: documentEnd - 1. Passing documentEnd itself is rejected with a message naming the last addressable index.

The fetch is a narrow field mask, not the whole document, including for tabbed documents (tabId=…). That is the difference from format='json', which returns the raw unpruned API response and is only for callers that genuinely need suggestions or style provenance — an oversized json read without maxLength now fails with a message pointing here instead of emitting a megabyte.

Large documents paginate at element boundaries: set maxResponseChars (default 100000, 0 disables), and when the response comes back truncated, call again with fromIndex set to the returned nextFromIndex. The Docs API has no start-index cursor, so each page costs one more (narrow) fetch.

Local Working Copies

readDocument (markdown format) saves what it reads to a local working-copy file, keyed by document ID and tab, so you can edit that file directly and push it back with replaceDocumentWithMarkdown using filePath instead of pasting content inline. replaceDocumentWithMarkdown also mirrors any inline markdown= push into that same file, so it always reflects what's actually on the document.

If the document contains content markdown can't represent (images, footnotes, a generated table of contents, or other Docs elements with no markdown equivalent), readDocument appends a warning after the markdown listing exactly what a full replaceDocumentWithMarkdown push would permanently remove. That warning is about a whole-body push: to rewrite one section of such a document, use replaceRangeWithMarkdown, which builds the same markdown structure inside a chosen range and checks fidelity only inside it, leaving the images and rules elsewhere alone.

These files live in a per-user directory under the OS temp dir (google-tools-mcp-<user>), created with restrictive permissions and checked on every write so a planted symlink is refused rather than followed. Set GOOGLE_MCP_WORKSPACE_DIR to use a different directory instead.

Configuration

On startup, configuration is loaded from these locations in order. A value is used from the first source that defines it:

Priority	Source
1	Real process environment, including an explicitly empty value
2	User config: `~/.config/google-tools-mcp/.env` (or `$XDG_CONFIG_HOME/google-tools-mcp/.env`)
3	`.env` in the server's current working directory
4	`.env` at the installed package root

GOOGLE_MCP_PROFILE selects the user config directory and must be set in the real process environment. It is ignored if placed in a .env file, with a startup warning. Missing config files are normal; an unreadable config file produces a warning naming its path.

This user-scoped file is particularly useful on Windows. MCP clients launched over stdio may not inherit a Windows user environment variable set after the client was started, while they can still read this file. Environment variables present in the spawned server always take precedence.

Keep .env readable only by your user: use chmod 600 on POSIX. On Windows, the default user-profile ACL is sufficient.

Environment Variables

Variable	Required	Description
`GOOGLE_CLIENT_ID`	No*	OAuth 2.0 Client ID
`GOOGLE_CLIENT_SECRET`	No*	OAuth 2.0 Client Secret
`GOOGLE_MCP_PROFILE`	No	Profile name for multi-account support (see above)
`GOOGLE_MCP_OAUTH_PORT`	No	Fixed loopback port for the interactive OAuth callback. Defaults to an ephemeral port; set a fixed port when forwarding the callback over SSH. See Remote OAuth with a persistent SSH tunnel.
`GOOGLE_MCP_TRANSPORT`	No	`stdio` (default) or `http`. Use `http` to run one shared server (see Shared HTTP mode and docs/http-mode.md)
`GOOGLE_MCP_PORT`	No	Port for HTTP transport (default `3939`)
`GOOGLE_MCP_ENDPOINT`	No	URL path for HTTP transport (default `/mcp`)
`GOOGLE_MCP_HTTP_TOKEN`	No	Overrides the private persistent HTTP token. Normally generated once at `<configDir>/http-token` and reused across restarts; never printed
`GOOGLE_MCP_HTTP_HOST`	No	Bind address for HTTP transport (default `127.0.0.1`). Only loopback hosts are accepted until supported TLS deployment exists
`GOOGLE_MCP_HTTP_ALLOWED_ORIGINS`	No	Comma-separated extra `Origin` values to accept (loopback origins are always allowed). Requests with a foreign browser `Origin` are otherwise rejected
`GOOGLE_MCP_HTTP_NO_AUTH`	No	Set to `1` to disable the bearer-token requirement. Only safe when you fully trust every process on the machine
`LOG_LEVEL`	No	`debug`, `info`, `warn`, `error`, or `silent`
`GOOGLE_MCP_LOG_FILE`	No	Plain log path. Defaults to `~/.config/google-tools-mcp/server.log`; set `0`, `false`, or `off` to disable, or set a custom path
`GOOGLE_MCP_JSONL_FILE`	No	Structured tool-call JSONL path. Defaults to `~/.config/google-tools-mcp/server.jsonl` (or alongside a custom plain log); set `0`, `false`, or `off` to disable
`GOOGLE_MCP_ENABLE_LEGACY_ALIASES`	No	Set to `true` to register the deprecated snake_case tool aliases (off by default; see Gmail tool migration)
`GOOGLE_MCP_WORKSPACE_DIR`	No	Overrides where local working copies of Google Docs are saved (see Local working copies). Defaults to a per-user directory under the OS temp dir
`SERVICE_ACCOUNT_PATH`	No	Path to service account JSON key (alternative to OAuth)
`GOOGLE_IMPERSONATE_USER`	No	Email to impersonate with service account
`GOOGLE_MCP_NO_UPDATE_CHECK`	No	Set to any value to skip the background check for a newer published version
`NO_UPDATE_NOTIFIER`	No	Same effect as `GOOGLE_MCP_NO_UPDATE_CHECK`, following the npm-ecosystem-standard opt-out name from the `update-notifier` package
`GOOGLE_MAPS_API_KEY`	No	Google Maps Platform API key (separate from OAuth). Without it, `maps` tools remain listed but fail with a clear error when called

* Not required as env vars if you provide credentials via .env file or credentials.json (see Step 2).

The background version check is also skipped automatically when CI is set to anything other than false, so automated test runs never make an unannounced outbound call.

Shared HTTP mode (one server for many clients)

By default the server uses stdio transport: each MCP client spawns its own google-tools-mcp process. If you run several clients at once (e.g. many editor or agent sessions), that's one Node process per session, each holding memory.

Run setup and choose One shared loopback server, or manage it directly with the supported lifecycle commands:

google-tools-mcp start
google-tools-mcp status
google-tools-mcp restart
google-tools-mcp stop

start attaches when the configured profile already has a healthy managed instance. serve is the foreground command for login items and service managers. State is published atomically to <configDir>/http-server.json; the stable 0600 bearer token lives at <configDir>/http-token. An occupied foreign port fails with a GOOGLE_MCP_PORT remedy instead of silently changing URLs.

Setup writes the different native client shapes: Claude Code gets an HTTP URL and authorization header, while Codex gets the URL plus --bearer-token-env-var GOOGLE_MCP_HTTP_TOKEN. Setup probes authenticated MCP discovery before changing either entry, so it never reports success over a dead server. See the operations reference for native manual registration and start-at-login examples.

Breaking change in 3.0.0: HTTP is stateless

The server speaks MCP 2026-07-28 on the official MCP TypeScript SDK v2. The whole HTTP session lifecycle is gone. stdio is unaffected — if you don't set GOOGLE_MCP_TRANSPORT, nothing in your config needs to change, with one exception. A Codex stdio registration needs CODEX_MCP_PROTOCOL_VERSION=2026-07-28 in its env block, because Codex pins stdio servers to the legacy lifecycle unless told otherwise. See the Codex section.

Removed, all returning 404 after the auth check:

GET /sse and its POST /messages companion (the legacy SSE compatibility transport the old runtime always stood up).
GET /ping, the old unauthenticated liveness route. Use authenticated GET /healthz, which returns exactly {"status":"ok","pid":<number>}, and 503 with {"status":"closed"} once the runtime has been shut down.
The GET that attached to a session's event stream and the DELETE that terminated a session.
The Mcp-Session-Id header. It is never required and never returned.

What's left is one POST endpoint (GOOGLE_MCP_ENDPOINT, default /mcp) plus authenticated GET /healthz.

The consequence for tools: read state is never carried between HTTP requests. Google Docs edits over HTTP take an explicit readHandle returned by readDocument — opaque, server-minted, single-use for a mutation, bound to the credential, profile, file, tab, revision, and structure, and expiring in under 24 hours. writeSpreadsheet, batchWrite, clearSpreadsheetRange, and deleteFile have no handle wiring yet and fail closed over HTTP; use stdio for those.

Full reference, including exact Claude Code and Codex reconfiguration steps (and the CODEX_MCP_PROTOCOL_VERSION=2026-07-28 env entry Codex needs): docs/http-mode.md.

Security

The HTTP endpoint exposes your authenticated Google Workspace tool surface (Gmail, Drive, Calendar, Docs, ...). It is guarded so it can't be driven by other processes or by web pages on your machine:

Bearer token required, on every route. Every request must send Authorization: Bearer <token>. One middleware runs ahead of routing, so the MCP endpoint, /healthz, and the 404 for every other path are all gated identically — an unauthenticated caller can't even probe which paths exist. A random token is generated once in the private config directory and reused; it is never printed or logged. GOOGLE_MCP_HTTP_TOKEN overrides that file. Requests without a valid token get 401.
Loopback only. Binds to 127.0.0.1 by default, so the port isn't reachable from the network. Non-loopback hosts are refused in every token mode until a supported TLS deployment boundary exists. Empty or whitespace-only hosts are refused too.
Origin checked. Requests carrying a non-loopback browser Origin are rejected (DNS-rebinding protection). Add trusted origins via GOOGLE_MCP_HTTP_ALLOWED_ORIGINS if needed.

Notes:

Use google-tools-mcp serve in a login item or user service. Cross-platform examples and failure recovery are in docs/http-mode.md.
Read-before-edit state is scoped to a single HTTP request and dies with it, so clients can't satisfy or clobber each other's guard state. They still share one process and one OAuth/token state, so a crash or token expiry affects everyone.
One process serves one configured Google profile and one effective service principal. Multiple profiles or horizontal scale are out of scope for this release.
stdio remains the setup default; shared HTTP is explicit opt-in.

Migrating from gdrive-tools-mcp / gmail-tools-mcp

This package replaces both gdrive-tools-mcp and gmail-tools-mcp. To migrate:

Replace both MCP server entries with a single google-tools-mcp entry
Re-authenticate (the combined server uses its own config dir at ~/.config/google-tools-mcp/)
All tools are available immediately — no discovery step needed

Gmail tool migration (snake_case → camelCase)

Gmail and Calendar tools were unified to camelCase, and the rarely-used Gmail account-config tools were consolidated into dispatch tools. Every old name still works as a deprecated alias that forwards to the new implementation, but the aliases are opt-in — they are not registered by default, since loading all 72 of them alongside the new camelCase + dispatch tools would grow the default tool surface instead of shrinking it. Set GOOGLE_MCP_ENABLE_LEGACY_ALIASES=true if you still depend on the old snake_case names.

Renamed (behavior and parameters unchanged)

Old name	New name
`send_message`	`sendMessage`
`reply_message`	`replyMessage`
`forward_message`	`forwardMessage`
`get_message`	`getMessage`
`list_messages`	`listMessages`
`modify_message`	`modifyMessage`
`delete_message`	`deleteMessage`
`trash_message`	`trashMessage`
`batch_get_messages`	`batchGetMessages`
`get_attachment`	`getAttachment`
`create_draft`	`createDraft`
`update_draft`	`updateDraft`
`delete_draft`	`deleteDraft`
`get_draft`	`getDraft`
`list_drafts`	`listDrafts`
`send_draft`	`sendDraft`
`get_thread`	`getThread`
`list_threads`	`listThreads`
`batch_get_threads`	`batchGetThreads`
`modify_thread`	`modifyThread`
`delete_thread`	`deleteThread`
`trash_thread`	`trashThread`
`get_profile`	`getProfile`
`watch_mailbox`	`watchMailbox`
`stop_mail_watch`	`stopMailWatch`
`list_calendars`	`listCalendars`
`get_events`	`getEvents`
`manage_event`	`manageEvent`
`get_busy`	`getBusy`
`get_free`	`getFree`
`move_event`	`moveEvent`
`list_recurring_event_instances`	`listRecurringEventInstances`
`manage_calendar`	`manageCalendar`

Consolidated into dispatch tools

Old name(s)	New dispatch call
`get_imap` / `update_imap`	`manageGmailSettings` resource=`imap` action=`get`/`update`
`get_pop` / `update_pop`	`manageGmailSettings` resource=`pop` action=`get`/`update`
`get_vacation` / `update_vacation`	`manageGmailSettings` resource=`vacation` action=`get`/`update`
`get_language` / `update_language`	`manageGmailSettings` resource=`language` action=`get`/`update`
`get_auto_forwarding` / `update_auto_forwarding`	`manageGmailSettings` resource=`autoForwarding` action=`get`/`update`
`list_forwarding_addresses` / `get_forwarding_address` / `create_forwarding_address` / `delete_forwarding_address`	`manageGmailSettings` resource=`forwardingAddress` action=`list`/`get`/`create`/`delete`
`list_delegates` / `get_delegate` / `add_delegate` / `remove_delegate`	`manageGmailSettings` resource=`delegate` action=`list`/`get`/`create`/`delete`
`list_send_as` / `get_send_as` / `create_send_as` / `patch_send_as` / `update_send_as` / `delete_send_as` / `verify_send_as`	`manageGmailSettings` resource=`sendAs` action=`list`/`get`/`create`/`patch`/`update`/`delete`/`verify`
`list_smime_info` / `get_smime_info` / `insert_smime_info` / `delete_smime_info` / `set_default_smime_info`	`manageSmime` action=`list`/`get`/`insert`/`delete`/`setDefault`
`list_filters` / `get_filter` / `create_filter` / `delete_filter`	`manageFilter` action=`list`/`get`/`create`/`delete`
`list_labels` / `get_label` / `create_label` / `patch_label` / `delete_label`	`manageLabel` action=`list`/`get`/`create`/`patch`/`delete`

License

MIT

Releasing

Maintainers: see RELEASING.md for the tag-triggered npm publishing workflow and its one-time trusted-publisher setup.

Name		Name	Last commit message	Last commit date
.claude/skills/live-agent-loop		.claude/skills/live-agent-loop
.github/workflows		.github/workflows
.planning		.planning
dist		dist
docs		docs
live		live
scripts		scripts
tests		tests
.env.live-smoke.example		.env.live-smoke.example
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
RELEASING.md		RELEASING.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

google-tools-mcp

Contents

Why google-tools-mcp?

Quick Start

Guided Setup (recommended)

Manual Setup

Step 1: Create Google OAuth Credentials

Step 2: Provide Your Credentials

Option A: Use credentials.json

Option B: Create a .env file

Option C: Set env vars in your MCP config

Step 3: Add to Your MCP Client

Local unpublished checkout

Codex

Claude Code

Project-Local Installation (with profile)

Other MCP clients

Step 4: Authenticate

Multi-Account Support

Troubleshooting

The google MCP server won't connect / "connection timed out"

Updates stop arriving after switching off npx

Development / Contributing

Tool Categories

files (27 tools)

documents (26 tools)

spreadsheets (30 tools)

email (16 tools)

email_threads (6 tools)

email_labels (1 tool)

email_settings (6 tools)

calendar (8 tools)

forms (6 tools)

slides (16 tools)

tasks (8 tools)

maps (6 tools)