@outfeedai/gmail-multi-mcp

Multi-account Gmail MCP server for Claude Code. Connect multiple Gmail accounts and access them directly from Claude.

No API keys. No configuration. Just install and connect.

Quick Start — Copy & Paste into Claude Code

Just paste this into Claude Code and it will set everything up for you:

Install the Gmail Multi MCP server by running these commands:
npm install -g @outfeedai/gmail-multi-mcp
claude mcp add gmail-multi-mcp -- gmail-multi-mcp

Then connect my Gmail account by running:
gmail-multi-mcp-setup setup

Manual Install

Step 1 — Install globally:

npm install -g @outfeedai/gmail-multi-mcp

Step 2 — Add to Claude Code:

claude mcp add gmail-multi-mcp -- gmail-multi-mcp

Step 3 — Connect a Gmail account:

gmail-multi-mcp-setup setup

Step 4 — Restart Claude Code and start using Gmail tools.

Don't have Node.js? Install it first: https://nodejs.org (LTS version)

Connect a Gmail Account

The first time you use a Gmail tool, Claude will prompt you to connect an account. Or you can set up accounts manually:

gmail-multi-mcp-setup setup

Your browser will open, asking you to sign in with Google and grant access. Once you click Allow, the account is connected and tokens are saved locally (encrypted).

Add Multiple Accounts

Run setup again for each account:

gmail-multi-mcp-setup setup

Each time, sign in with a different Gmail account. All accounts are stored locally and accessible from Claude Code.

Manage Accounts

# List all connected accounts (* = primary)
gmail-multi-mcp-setup accounts

# Set a different primary account
gmail-multi-mcp-setup primary [email protected]

# Remove an account
gmail-multi-mcp-setup remove [email protected]

Available Tools

Once installed, Claude Code has access to these tools:

| Tool | Description | |------|-------------| | Email | | | gmail_search | Search emails using Gmail search syntax (e.g. from:[email protected], is:unread, subject:invoice) | | gmail_read | Read a full email by ID (subject, body, attachments) | | gmail_read_thread | Read all messages in an email thread | | gmail_send | Send an email (supports HTML, CC, BCC, reply-to-thread) | | Drafts | | | gmail_list_drafts | List draft emails in an account | | gmail_create_draft | Create a new draft email (supports HTML, CC, BCC) | | gmail_update_draft | Update an existing draft | | gmail_send_draft | Send a draft | | gmail_delete_draft | Permanently delete a draft | | Labels | | | gmail_list_labels | List all labels in an account | | gmail_modify_labels | Add or remove labels from an email | | Accounts | | | gmail_list_accounts | List all connected Gmail accounts | | gmail_set_primary | Set the default account | | gmail_remove_account | Remove a connected account |

Every tool accepts an optional account parameter to specify which Gmail account to use. If omitted, the primary account is used.

Multi-Account Usage

When talking to Claude, you can specify which account to use:

• "Search my work email for invoices" - uses primary account
• "Search [email protected] for emails from HR" - uses specified account
• "Send an email from my personal Gmail" - Claude will ask which account or you can specify

Example Prompts

Search my Gmail for unread emails from the last week
Read the latest email from [email protected]
Send an email to [email protected] with subject "Meeting Notes" and a summary of today's discussion
Find all emails with attachments from last month
Reply to the latest thread from [email protected]

Use Your Own Google API Credentials (Optional)

By default, this package ships with shared Google OAuth credentials so it works out of the box. You can swap in your own Client ID and Secret — useful if you want full control, higher quota, or you're deploying to a team with stricter policies.

1. Create your OAuth credentials in Google Cloud

1. Go to https://console.cloud.google.com/ and create (or pick) a project.
2. Enable the Gmail API: APIs & Services → Library → search Gmail API → Enable.
3. Configure the OAuth consent screen: APIs & Services → OAuth consent screen.
   • User type: External
   • Fill in app name, support email, developer contact.
   • Add the following scopes:
     • https://www.googleapis.com/auth/gmail.readonly
     • https://www.googleapis.com/auth/gmail.send
     • https://www.googleapis.com/auth/gmail.modify
     • https://www.googleapis.com/auth/gmail.labels
   • IMPORTANT — Set publishing status to Production. Click Publish App on the OAuth consent screen. If it stays in Testing mode, Google forces your refresh tokens to expire after 7 days and you'll have to reconnect every week. Production mode keeps tokens valid indefinitely. You do not need to go through Google's app verification for personal/internal use — you can publish unverified and just accept the "unverified app" warning during sign-in.
4. Create the OAuth Client ID: APIs & Services → Credentials → Create Credentials → OAuth client ID.
   • Application type: Desktop app (or Web application)
   • If Web application: add authorized redirect URI exactly:

     http://localhost:9876/callback

5. Copy your Client ID and Client Secret.

2. Add your credentials to Gmail Multi MCP

Option A — Interactive (recommended):

gmail-multi-mcp-setup set-credentials

You'll be prompted to paste your Client ID and Client Secret. They're stored locally at ~/.outfeedai/credentials.json with owner-only permissions.

Option B — Arguments:

gmail-multi-mcp-setup set-credentials <CLIENT_ID> <CLIENT_SECRET>

Option C — Environment variables (take priority over the config file):

export GMAIL_MCP_CLIENT_ID="your-client-id"
export GMAIL_MCP_CLIENT_SECRET="your-client-secret"

3. Connect an account

After saving credentials, run setup to connect a Gmail account with your new OAuth app:

gmail-multi-mcp-setup setup

Inspect or reset

gmail-multi-mcp-setup show-credentials    # shows which source is active
gmail-multi-mcp-setup reset-credentials   # deletes custom, falls back to default

Security

• OAuth tokens are encrypted at rest using AES-256-GCM
• Tokens are stored locally at ~/.outfeedai/gmail-tokens.enc
• Custom OAuth credentials (if set) are stored at ~/.outfeedai/credentials.json (mode 600)
• File permissions are locked down (owner read/write only)
• No data is sent to any third-party server — all communication is directly between your machine and Google's API

Requirements

• Node.js 20+
• Claude Code

Troubleshooting

MCP server shows "Connection closed" Restart Claude Code. If it persists, clear the npx cache and try again:

claude mcp remove gmail-multi-mcp
npm install -g @outfeedai/gmail-multi-mcp
claude mcp add gmail-multi-mcp -- gmail-multi-mcp

"No Gmail accounts configured" Run the setup flow:

gmail-multi-mcp-setup setup

OAuth error or "access_denied" Make sure you're signing in with a Google account that has Gmail enabled. If the issue persists, remove the account and re-add it.

Built by OutfeedAI