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

Tool	Description
list_accounts	List all authenticated Gmail accounts
initiate_auth	Start OAuth flow — returns a URL to open in browser
complete_auth	Finalize auth after completing Google sign-in
remove_account	Remove an account and its stored credentials

Reading Email

Tool	Description
search_emails	Search with Gmail syntax (is:unread, from:, after:, etc.)
get_email	Fetch full email content by message ID

Writing Email

Tool	Description
send_email	Send an email (supports To, CC, BCC)
reply_to_email	Reply in thread, preserving References headers
create_draft	Save an email as a draft

Organization

Tool	Description
list_labels	List all Gmail labels for an account
add_label	Add one or more labels to a message
remove_label	Remove one or more labels from a message
archive_email	Remove from Inbox
mark_as_read	Remove the UNREAD label
mark_as_unread	Add the UNREAD label

---

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

... [View full README on GitHub](https://github.com/gx-55/multi-gmail-mcp#readme)