Google Tools Mcp

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

153 tools for Drive, Docs, Sheets, Gmail, Calendar, and Forms — 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 and it works.
• One login for everything. A single OAuth flow gives you Drive, Docs, Sheets, Gmail, Calendar, and Forms. 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.
• 153 tools, zero config. Every tool is available the moment the server starts. Send emails, create docs, manage calendar events, build forms — 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

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

{
  "mcpServers": {
    "google": {
      "command": "npx",
      "args": ["-y", "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

Codex

codex mcp add google -- npx -y 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 \
  -- npx -y google-tools-mcp

Claude Code

User-scope (available in all projects):

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

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

claude mcp add google -- npx -y 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 \
  -- npx -y google-tools-mcp

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

Project-Local Installation (with profile)

Via the claude CLI:

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

Or manually in your .mcp.json:

{
  "mcpServers": {
    "google": {
      "command": "npx",
      "args": ["-y", "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": "npx",
      "args": ["-y", "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.

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.

Tool Categories

files (18 tools)

Google Drive file management and content reading.

listDriveFiles, searchDocuments, getFileInfo, getFilePath, createFolder, listFolderContents, getFolderInfo, moveFile, copyFile, renameFile, deleteFile, createDocument, createDocumentFromTemplate, listSharedDrives, listSharedWithMe, downloadFile, readFile, searchFileContents

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 (29 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

email (19 tools)

Gmail messages and drafts.

send_message, reply_message, forward_message, get_message, list_messages, modify_message, delete_message, trash_message, untrash_message, batch_delete_messages, batch_modify_messages, batch_get_messages, get_attachment, create_draft, update_draft, delete_draft, get_draft, list_drafts, send_draft

email_threads (7 tools)

Gmail thread-level operations.

get_thread, list_threads, batch_get_threads, modify_thread, delete_thread, trash_thread, untrash_thread

email_labels (6 tools)

Gmail label management.

create_label, delete_label, get_label, list_labels, patch_label, update_label

email_settings (37 tools)

Gmail admin and configuration.

get_auto_forwarding, update_auto_forwarding, get_imap, update_imap, get_language, update_language, get_pop, update_pop, get_vacation, update_vacation, add_delegate, remove_delegate, get_delegate, list_delegates, create_filter, delete_filter, get_filter, list_filters, create_forwarding_address, delete_forwarding_address, get_forwarding_address, list_forwarding_addresses, create_send_as, delete_send_as, get_send_as, list_send_as, patch_send_as, update_send_as, verify_send_as, delete_smime_info, get_smime_info, insert_smime_info, list_smime_info, set_default_smime_info, get_profile, watch_mailbox, stop_mail_watch

calendar (8 tools)

Google Calendar — events, availability, and calendar management.

list_calendars, get_events, manage_event, get_busy, get_free, move_event, list_recurring_event_instances, manage_calendar

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

Environment Variables

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

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

License

MIT