Gmail MCP Server

Multi-account Gmail integration for AI assistants via the Model Context Protocol (MCP).

Give your AI assistant secure access to all your Gmail accounts -- search, read, triage, draft, label, archive, trash-stage, and send emails with per-account routing, macOS Keychain token storage, and two-step confirmation flows for sensitive actions.

The Problem

Built-in Gmail integrations for AI assistants have significant limitations:

• Single account only -- no way to switch between personal, work, and business inboxes

• Insecure token storage -- most open-source servers store OAuth tokens as plaintext JSON files

• Overly broad scopes -- many request full mail.google.com access (read, write, delete, send)

• No send protection -- an AI can compose and send an email in a single step with no human checkpoint

What This Server Does Differently

Features

• 35 tools for serious Gmail and Workspace workflows: search/read, batch read, thread reads, draft create/update/list, forwarding, labels, filters, archive, staged trash, staged bulk labeling, profile, attachments, two-step send, Google Docs/Drive reads, and scoped Drive writes

• Multi-account routing -- every tool accepts an optional account parameter (email or alias)

• Active account -- set a default account that persists across restarts

• Rich draft bodies -- create/update drafts can include raw html_body with a plain-text fallback for Gmail-safe formatted replies

• Safe modify -- label/archive/trash operations require explicit message IDs or staged query preview/confirmation

• Attachment handling -- downloads to a sandboxed quarantine directory with SHA-256 integrity hashes and read-only permissions

• Minimal dependencies -- only the official Google APIs, MCP SDK, and Zod

Quick Start

Prerequisites

• Node.js 18+ (tested on 22)

• macOS (uses Keychain for token storage)

• A Google Cloud project with OAuth credentials

Install & Build

git clone https://github.com/arkaigrowth/gmail-mcp-server.git
cd gmail-mcp-server
npm install
npm run build

Smoke Test

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js

You should see a JSON response listing all 35 tools.

Add to Your AI Assistant

Claude Code (~/.claude/settings.json under mcpServers):

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

Claude Desktop (claude_desktop_config.json):

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

Authenticate Your First Account

Once the MCP server is connected, tell your AI assistant:

"Authenticate my Gmail account user@gmail.com with alias personal"

This will:

1. Open your browser to Google's consent screen

2. Store the OAuth refresh token in your macOS Keychain

3. Register the account for future use

You can then immediately start using it:

"Search my personal inbox for emails from GitHub in the last week"

Google Cloud Setup

You need a Google Cloud OAuth client (type: "Desktop app") with the Gmail API enabled. Each Google account needs its own OAuth client from a project where that account has access.

Step-by-step

1. Go to the Google Cloud Console

2. Create a new project (or use an existing one)

3. Enable the Gmail API: APIs & Services > Library > search "Gmail API" > Enable

4. Configure the OAuth consent screen: APIs & Services > OAuth consent screen

   • User type: External (or Internal if using Google Workspace)

   • Add the Gmail scopes: gmail.readonly, gmail.compose, gmail.modify, gmail.settings.basic

   • Add the Workspace scopes used by the Docs/Drive tools: documents.readonly, documents, drive.metadata.readonly, drive.readonly, drive.file

   • Add your email as a test user (while in "Testing" status)

5. Create OAuth credentials: APIs & Services > Credentials > Create Credentials > OAuth client ID

   • Application type: Desktop app

   • Download the JSON file

6. Save the JSON file as ~/.gmail-mcp/client_secret.json

Tip: If you have multiple Google accounts, you can specify a per-account path via the client_secret_path parameter when authenticating.

Credential File Lookup Order

1. client_secret_path parameter passed to gmail_authenticate

2. Path stored in the account's config (accounts.json)

3. GMAIL_MCP_CLIENT_SECRET_PATH environment variable

4. ~/.gmail-mcp/client_secret.json (default)

Tool Reference

Account Management

Email Operations

Labels, Archive, Trash

Gmail filters

Filter label names must already exist. The server returns available label names when a requested name cannot be resolved, and does not auto-create labels.

Compose & Send

Attachments

All email tools accept an optional account parameter (email or alias). If omitted, the active default account is used. If no default is set and only one account exists, it's auto-selected.

Draft bodies are plain text by default. For rich Gmail rendering, pass html_body with body as the plain-text fallback; the server emits multipart/alternative with text/plain first and text/html second. You can also set content_type: "text/html" to treat body as raw HTML when no separate fallback is available. Outbound attachments are not supported in draft create/update yet.

Security

Token Storage

OAuth tokens (refresh tokens, client credentials) are stored exclusively in the macOS Keychain using the security CLI. No plaintext token files are ever written to disk.

Keychain Service: gmail-mcp-server
Keychain Account: <your-email-address>

The ~/.gmail-mcp/accounts.json config file stores only metadata (email, alias, description, credential file path) -- never secrets.

OAuth Scopes

The consent flow requests one combined set of scopes (REQUIRED_AUTH_SCOPES in src/scopes.ts). It covers Gmail plus the Google Docs and Drive tools this server also exposes (reading shared docs and specs, and writing scoped Docs/Drive files), so the Workspace scopes are requested in the same flow.

Gmail scopes

Google Docs / Drive scopes

The Gmail scopes are intentionally narrower than mail.google.com full access: the server does not request gmail.send; direct messages.send is blocked and all sends must go through draft staging plus confirmation. The Workspace scopes add Docs/Drive read and scoped-write access on top of that.

The scopes are defined as grouped constants in src/scopes.ts (REQUIRED_GMAIL_SCOPES, REQUIRED_WORKSPACE_READ_SCOPES, REQUIRED_WORKSPACE_WRITE_SCOPES). If you only need the Gmail tools, remove the Workspace groups from REQUIRED_AUTH_SCOPES and rebuild; the consent flow then requests only the Gmail scopes and the Docs/Drive tools stop working.

Tokens store the granted scope list in Keychain metadata. Tokens granted before a scope was added produce a clear reauth-required error for the tools that need it; rerun gmail_authenticate for that account.

Re-authentication required: Adding gmail.settings.basic means each account must rerun gmail_authenticate and complete the consent flow before filter tools work. Existing tokens keep working for old tools, but filter calls fail with insufficient scopes until re-authentication.

Two-Step Send Confirmation

Sending email requires two separate tool calls:

1. gmail_send_draft -- stages the draft and returns a 16-character cryptographic confirmation code (valid for 60 seconds)

2. gmail_confirm_send -- the AI must present the code back, and the account must match

Additionally, messages.send is explicitly blocked on the Gmail client -- all sends must go through the draft confirmation flow.

Two-Step Trash And Bulk Label Confirmation

Trash and query-based bulk label operations use short-lived, account-bound confirmation codes. Explicit message ID label/archive operations are direct because their targets are already selected; query-based bulk labeling always previews before mutation.

OAuth Callback Security

• Callback server binds to 127.0.0.1 only (never 0.0.0.0)

• Random state parameter validated to prevent CSRF

• Callback server auto-terminates after 5 minutes by default (override via GMAIL_MCP_AUTH_TIMEOUT_MS)

• Dynamic port allocation (no fixed ports)

Attachment Quarantine

Downloaded attachments are:

• Saved to ~/.gmail-mcp/quarantine/<messageId>/ with 0o700 directory permissions

• Written with 0o400 (read-only) file permissions

• Filename sanitized to prevent path traversal

• Accompanied by a SHA-256 hash for integrity verification

Shell Injection Prevention

All calls to the macOS security CLI use execFileSync with argument arrays, not execSync with string interpolation. This prevents shell injection via crafted email addresses or token data.

Multi-Account Examples

Setup two accounts

"Authenticate user@gmail.com with alias personal"
"Authenticate work@company.com with alias work, client_secret_path ~/.gmail-mcp/work_client_secret.json"

Switch between them

"Switch to my work account"
"Search work for emails from the finance team this month"
"Switch to personal"
"Read my latest emails"

Or specify per-call

"Search my personal inbox for order confirmations"
"Search my work inbox for meeting invites tomorrow"

File Structure

~/.gmail-mcp/
  accounts.json          # Account metadata (no secrets)
  defaults.json          # Active account preference
  client_secret.json     # Default OAuth client credentials (from Google)
  quarantine/            # Downloaded attachments (sandboxed)
    <messageId>/
      attachment.pdf     # Read-only (0o400)

macOS Keychain
  Service: gmail-mcp-server
  Account: user@gmail.com    # Token JSON, including granted OAuth scopes
  Account: work@company.com  # Token JSON, including granted OAuth scopes

Development

# Build
npm run build

# Run in development (with tsx)
npm run dev

# Run tests
npm test

# Smoke test (JSON-RPC)
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js

Project Structure

src/
  index.ts          # Entry point: MCP server + stdio transport
  tools.ts          # 35 tool registrations with Zod schemas
  gmail-client.ts   # Gmail API wrapper (search, read, draft, labels, filters, archive, trash, send, attachments)
  accounts.ts       # Account config management (load, resolve, persist)
  keychain.ts       # macOS Keychain integration via security CLI
  oauth.ts          # OAuth browser flow with localhost callback
  scopes.ts         # Gmail OAuth scope constants and metadata checks
  types.ts          # Shared TypeScript interfaces
skills/
  gmail-multi/      # Repo-local workflow guidance for agents using this server

Platform Support

Currently macOS only due to the Keychain dependency. Contributions for Linux (secret-tool / libsecret) and Windows (wincred) credential storage are welcome.

License

MIT