io.github.gx-55/multi-gmail-mcp

multi-gmail-mcp

A Model Context Protocol (MCP) server that lets Claude Desktop manage multiple Gmail accounts simultaneously. Listed on the official Anthropic MCP registry and published on npm.

Features

• Connect unlimited Gmail accounts — personal, work, side projects
• Search any inbox using full Gmail search syntax
• Read complete emails with MIME parsing
• Send, reply in thread, and create drafts
• Organize with labels: add, remove, list, archive
• Mark as read / unread
• Tokens stored locally in ~/.gmail-mcp-tokens.db — never committed to git
• Auto-refreshes OAuth tokens silently

Requirements

• Node.js >= 22.5.0
• A Google Cloud project with the Gmail API enabled
• Claude Desktop

Installation

npm install -g multi-gmail-mcp

This registers two global commands: gmail-mcp (the MCP server) and gmail-mcp-cli (account manager).

Google Cloud Setup

You only need to do this once.

1. Go to console.cloud.google.com → create a project
2. Enable the Gmail API (APIs & Services → Library)
3. Configure the OAuth consent screen — External, add your Gmail addresses as test users
4. Add scopes: gmail.readonly, gmail.send, gmail.modify, gmail.labels
5. Create a Desktop app OAuth credential → download the JSON
6. Save it to ~/.gmail-mcp-oauth.json

Alternatively, set environment variables in the Claude Desktop config (see below).

Authenticating Gmail Accounts

# Add accounts (opens browser for Google sign-in)
gmail-mcp-cli add personal@gmail.com
gmail-mcp-cli add work@company.com

# List authenticated accounts
gmail-mcp-cli list

# Remove an account
gmail-mcp-cli remove work@company.com

Tokens are saved to ~/.gmail-mcp-tokens.db and refreshed automatically.

Claude Desktop Configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "multi-gmail": {
      "command": "gmail-mcp"
    }
  }
}

If you prefer environment variables over ~/.gmail-mcp-oauth.json:

{
  "mcpServers": {
    "multi-gmail": {
      "command": "gmail-mcp",
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Restart Claude Desktop after saving. Click the hammer icon to confirm 19 tools are loaded.

Available Tools

Account Management

Reading Email

Writing Email

Organization

Example Prompts

List all my authenticated Gmail accounts.

Search my work@company.com inbox for unread emails from this week.

Reply to that email from my personal account saying I'll be there Saturday.

Send an email from personal@gmail.com to friend@example.com
with subject "Dinner plans" and body "Are you free Saturday?"

Archive everything older than a week in my side-project inbox that's already read.

Check both my accounts for emails from GitHub and summarize them.

Security

• ~/.gmail-mcp-oauth.json and ~/.gmail-mcp-tokens.db live in your home directory — outside the project, never committed
• .gitignore excludes *.db, .gmail-mcp-oauth.json, and .env
• The server runs over stdio only — no network port is opened
• OAuth scopes are limited to the minimum required

See SECURITY.md for full details: token storage, network behavior, scope rationale, revocation steps, and how to report a vulnerability.

Registry

Listed on the official Anthropic MCP registry:

io.github.gx-55/multi-gmail-mcp

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.gx-55"

Project Structure

multi-gmail-mcp/
├── bin/
│   ├── gmail-mcp.js        # Entry point for the MCP server command
│   └── gmail-mcp-cli.js    # Entry point for the CLI command
├── src/
│   ├── server.js           # MCP server — all 19 tools
│   ├── gmail-client.js     # Gmail API wrapper
│   ├── auth.js             # OAuth2 flow with auto-refresh
│   ├── db.js               # SQLite token storage (node:sqlite)
│   └── cli.js              # Account management CLI
└── package.json

Troubleshooting

"No OAuth credentials found" Make sure ~/.gmail-mcp-oauth.json exists or set GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET in the Claude Desktop config.

"Account not found. Authenticate it first" Run gmail-mcp-cli add your@gmail.com before using that account in Claude.

Tools not appearing in Claude Desktop Confirm gmail-mcp is in your PATH (which gmail-mcp) and restart Claude Desktop.

Token expired errors Tokens auto-refresh if a valid refresh token is stored. If refresh fails, remove the account and re-authenticate: gmail-mcp-cli remove your@gmail.com && gmail-mcp-cli add your@gmail.com.