Google Tools MCP README

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

Contents

• Quick Start
• Production OAuth setup
• Privacy policy
• Tool Categories
• Common Workflows
• Local Working Copies
• Environment Variables
• Shared HTTP mode
• Troubleshooting
• Development / Contributing

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.
• Saved authorization. No browser popup until your first tool call. The token is saved for reuse; production OAuth setup avoids Testing's seven-day expiry. Revocation or permission changes can still require consent 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:

1. Enabling all required Google APIs (opens in your browser)
2. Configuring the OAuth consent screen
3. Creating OAuth credentials
4. 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).

For ongoing use without weekly Google consent, follow Production OAuth setup. It covers publishing status, homepage and privacy-policy URLs, and when Google verification is required.

Manual Setup

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

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

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

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

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.

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.

manageGmailSettings (resource: imap | pop | vacation | language | autoForwarding | forwardingAddress | delegate | sendAs), manageSmime, manageFilter, getProfile, watchMailbox, stopMailWatch

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:

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

* 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. Sheets value writes (writeSpreadsheet, batchWrite, and clearRange) take a handle from a bounded readSpreadsheet range read; use ranges for a multi-range batch baseline. getSpreadsheetInfo returns a structure handle for sheet/table/chart deletion, while readCellFormat returns a bounded format/validation handle for formatCells, copyFormatting, and setDropdownValidation. deleteTable(deleteData: true) uses a value handle for its actual cleared cells. getFileInfo returns the metadata handle required by deleteFile. Sheets and Drive reread before mutating but have no Docs-style atomic conditional-write API; see the HTTP resource-handle contract.

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:

1. Replace both MCP server entries with a single google-tools-mcp entry
2. Re-authenticate (the combined server uses its own config dir at ~/.config/google-tools-mcp/)
3. 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)

Consolidated into dispatch tools

License

MIT

Releasing

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