gmail-multi-mcp

Seamless multi-account Gmail integration for AI assistants via the Model Context Protocol (MCP). Manage 2 to 20+ Gmail accounts concurrently in a single process without context explosion.

Why gmail-multi-mcp?

Traditional Gmail MCP servers spawn one background process per account, duplicating 15–20 tool definitions in your LLM's system prompt for every inbox. With 5 accounts, that's nearly 100 tools cluttering the context window.

gmail-multi-mcp provides a unified multi-account architecture:

• 🚀 Single Process for N Accounts: Runs 1 lightweight process whether you have 2 or 10 accounts. Only 10 tools are registered in your prompt.

• 🔍 Parallel Cross-Account Search: Search across all your inboxes at once using account="all" (queries all inboxes concurrently with Promise.allSettled).

• 🛡️ Per-Account Permission Tiers: Set sensitive work inboxes to draft (compose only) or readonly while keeping personal inboxes on full (send allowed).

• 🔄 Hot-Reloading: Add new accounts via CLI while your AI assistant is running—new accounts are detected immediately without restarting your client.

• 📎 Full Attachment Support: Download attachments to local folders and attach local files to outgoing emails or drafts.

• 🔒 Zero Third-Party Relays: Direct communication between your local machine and Google APIs using official SDKs. Tokens are stored locally with strict 0600 permissions.

Related MCP server: Gmail MCP Server

Quick Start

1. Prerequisites & Google Cloud OAuth Setup

To access the Gmail API, you need a Google Cloud OAuth Desktop Client:

1. Go to the Google Cloud Console and create a project (e.g. gmail-mcp).

2. Navigate to APIs & Services > Library and enable the Gmail API.

3. Go to APIs & Services > OAuth consent screen:

   • Choose External (or Internal if using a Google Workspace organization).

   • Fill in the required app information and add your email addresses as Test users.

4. Go to APIs & Services > Credentials > Create Credentials > OAuth client ID:

   • Application type: Desktop app.

   • Download the generated JSON credentials file.

5. Save the file to the default configuration directory:

   mkdir -p ~/.gmail-multi-mcp
   chmod 700 ~/.gmail-multi-mcp
   mv ~/Downloads/client_secret_*.json ~/.gmail-multi-mcp/gcp_client_secret.json
   chmod 600 ~/.gmail-multi-mcp/gcp_client_secret.json

2. Connect Your Accounts

Use the CLI to connect your accounts. Each command opens a browser tab for one-time Google Sign-in:

# Connect primary personal account (default: full permissions)
npx gmail-multi-mcp auth add personal

# Connect work account with draft-only safety (cannot send or trash emails)
npx gmail-multi-mcp auth add work --permission draft

# Connect an account using a custom corporate OAuth client JSON
npx gmail-multi-mcp auth add corp --oauth-keys ~/Downloads/corp-oauth.json

# View all connected accounts
npx gmail-multi-mcp auth list

3. Add to Your MCP Client Configuration

Antigravity (~/.gemini/config/mcp_config.json)

{
  "mcpServers": {
    "gmail-multi": {
      "command": "npx",
      "args": ["-y", "gmail-multi-mcp"]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "gmail-multi": {
      "command": "npx",
      "args": ["-y", "gmail-multi-mcp"]
    }
  }
}

Cursor (Settings > Features > MCP)

• Name: gmail-multi

• Type: command

• Command: npx -y gmail-multi-mcp

Permission Tiers

Configure permissions per account when adding it or change it anytime:

npx gmail-multi-mcp auth set-permission work draft

Available Tools

CLI Reference

# Add a new account
gmail-multi-mcp auth add <alias> [--permission <readonly|draft|full>] [--oauth-keys <path>]

# List all connected accounts
gmail-multi-mcp auth list

# Update account permissions dynamically without re-login
gmail-multi-mcp auth set-permission <alias> <readonly|draft|full>

# Remove an account and delete its local token
gmail-multi-mcp auth remove <alias>

Directory Structure & Security

All local tokens and configuration files are stored outside project directories:

~/.gmail-multi-mcp/
├── gcp_client_secret.json  # Default OAuth client secret (chmod 0600)
├── accounts.json           # Account registry and metadata (chmod 0600)
└── tokens/                 # Encrypted OAuth refresh tokens per account (chmod 0600)
    ├── personal.json
    └── work.json

• File Permissions: Created with 0700 (directory) and 0600 (files), ensuring only your local OS user can read them.

• Custom Location: Set GMAIL_MULTI_MCP_DIR=/path/to/custom/dir to override the default storage directory.

Development

# Clone the repository
git clone https://github.com/your-username/gmail-multi-mcp.git
cd gmail-multi-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

# Test CLI
node dist/index.js auth list

License

MIT © 2026