google-tools-mcp

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

156 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.
156 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 (this package pulls in fastmcp + the full googleapis client library). 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 mcp add google -- google-tools-mcp

With env vars (Option C):

codex mcp add google \
  --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 (this package pulls in fastmcp + the full googleapis client library, a large node_modules) 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". google-tools-mcp itself also logs its own startup time on the server's first ready line (e.g. MCP Server running using stdio in 1123ms), so if the server logs a fast startup but the client still reports a near-30000ms connection time, the delay is happening before the server process even starts, i.e. in npx, not in the server.

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.

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` (22 tools)

Google Docs read/write/format with markdown support.

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

`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 152 service-specific tools. Four general utilities — help, logout, troubleshoot, and feedback — bring the default server surface to 156 tools. See Common Workflows for practical examples.

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. Use modifyText or appendMarkdown instead for those documents.

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.

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)
`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	Bearer token required by HTTP clients. If unset in HTTP mode, a one-time token is generated and printed to stderr at startup. Set a fixed value to keep it stable across restarts
`GOOGLE_MCP_HTTP_HOST`	No	Bind address for HTTP transport (default `127.0.0.1`, loopback only). Change only if you deliberately need remote access
`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	Set to `1` to log to `~/.config/google-tools-mcp/server.log`, or set to a custom file path
`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.

Set GOOGLE_MCP_TRANSPORT=http to instead run a single long-lived server that every client shares over a loopback URL — one process regardless of how many clients connect:

# start one shared server (keep it running; e.g. a login item or service)
GOOGLE_MCP_TRANSPORT=http GOOGLE_MCP_PORT=3939 GOOGLE_MCP_HTTP_TOKEN=your-secret google-tools-mcp

Then point each client at the URL, sending the token as a bearer header:

{
  "mcpServers": {
    "google": {
      "type": "http",
      "url": "http://127.0.0.1:3939/mcp",
      "headers": { "Authorization": "Bearer your-secret" }
    }
  }
}

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>, including the GET that attaches to a session's event stream, the DELETE that terminates one, and the legacy SSE compatibility routes (/sse and its /messages POST endpoint) that FastMCP's HTTP transport always stands up alongside the configured endpoint, whatever GOOGLE_MCP_ENDPOINT is set to — there is no way to disable them, so they're guarded instead. A leaked session id on its own gets nobody in. Set GOOGLE_MCP_HTTP_TOKEN; if you don't, a random one-time token is generated and printed to stderr at startup (printed directly, so it still appears under LOG_LEVEL=error or LOG_LEVEL=silent). Requests without a valid token get 401. (GOOGLE_MCP_HTTP_NO_AUTH=1 disables this — only on a fully trusted machine.) The /ping health endpoint stays open.
Loopback only. Binds to 127.0.0.1 by default, so the port isn't reachable from the network. Override with GOOGLE_MCP_HTTP_HOST only if you know you need to. Startup refuses to run (and exits non-zero) if GOOGLE_MCP_HTTP_NO_AUTH=1 is combined with a non-loopback host such as 0.0.0.0 or :: — that combination would be a remotely reachable, completely unauthenticated server — and refuses an empty or whitespace-only host as well.
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:

The shared server does not start or stop with your clients — you manage its lifecycle (start it at login / run it as a service).
Each connecting client gets its own MCP session, and per-session state (such as the read-before-edit guard) is isolated between clients. They still share one process and one OAuth/token state, so a crash or token expiry affects everyone.
Auth (google-tools-mcp auth / setup) is unchanged and still uses stdio.

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
Latest commit History 233 Commits
.github/workflows		.github/workflows
dist		dist
docs		docs
scripts		scripts
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.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

Folders and files

Latest commit

History

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 (22 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)