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
• 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.
• 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:

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).

Manual Setup

<details> <summary>Click to expand manual setup instructions</summary>

Step 1: Create Google OAuth Credentials

1. Go to the Google Cloud Console
2. Create a project (or use an existing one)
3. 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
4. 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.
5. Go to Credentials → Create Credentials → OAuth Client ID
6. Select Desktop application as the application type
7. 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

</details>

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 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.

<details> <summary>Prefer <code>npx</code> anyway, or can't install globally?</summary>

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.

</details>

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