Advanced Gmail Mcp

Gmail MCP Server

A Gmail MCP server for Claude Code that provides full email management across multiple Gmail accounts.

Features

• 12 tools: list, search, read, thread, labels, send, draft, reply, archive, label, trash, batch modify
• Multi-account support with simple aliases
• OAuth2 authentication with interactive CLI flow
• Token auto-refresh — re-authenticates transparently
• Rate limit retry with exponential backoff
• Claude Code commands included (/email and /checkemail) for structured inbox triage

Quick Start

1. Clone & Install

git clone https://github.com/coreyepstein/advanced-gmail-mcp.git
cd advanced-gmail-mcp
npm install

2. Google Cloud Setup

1. Go to Google Cloud Console
2. Create a new project (or select an existing one)
3. Enable the Gmail API:

• APIs & Services → Enable APIs → search "Gmail API" → Enable

1. Configure the OAuth consent screen:

• APIs & Services → OAuth consent screen
• User type: External (or Internal if using Google Workspace)
• Add your email address(es) as test users
• Add scopes: gmail.readonly, gmail.modify, gmail.send, gmail.compose

1. Create OAuth credentials:

• APIs & Services → Credentials → Create Credentials → OAuth client ID
• Application type: Desktop app
• Download the JSON file

1. Save the downloaded file as credentials.json in the project root

3. Configure Accounts

cp accounts.example.json accounts.json

Edit accounts.json with your Gmail accounts:

{
  "accounts": [
    { "email": "you@gmail.com", "alias": "personal" },
    { "email": "you@company.com", "alias": "work" }
  ],
  "default": "personal"
}

You can add as many accounts as you want. Each needs a unique alias.

4. Authenticate

# Authenticate all accounts (opens browser for each)
npm run auth

# Or authenticate a single account
npm run auth -- work

# Check auth status
npm run auth:check

The auth flow opens a browser window for each account. Tokens are saved to ./tokens/.

5. Add to Claude Code

Add to your MCP config (project .mcp.json or ~/.claude.json):

{
  "mcpServers": {
    "gmail": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/gmail-mcp/src/server.ts"]
    }
  }
}

> Important: Use the absolute path to src/server.ts.

6. (Optional) Add Commands

Copy the included Claude Code commands for structured email workflows:

# From your project root (where .claude/ lives)
mkdir -p .claude/commands
cp /path/to/gmail-mcp/.claude/commands/email.md .claude/commands/
cp /path/to/gmail-mcp/.claude/commands/checkemail.md .claude/commands/

Then use /email or /checkemail in Claude Code.

Tools

| Tool | Description | |------|-------------| | list_emails | List inbox or label emails | | search_emails | Search with Gmail query syntax | | read_email | Read full email by ID | | get_thread | Get full thread with all messages | | get_labels | List all labels | | send_email | Send a new email | | draft_email | Create a draft | | reply_email | Reply with proper threading | | archive_email | Archive (remove INBOX label) | | label_email | Add/remove labels | | trash_email | Move to trash | | batch_modify | Batch archive/trash/label |

All tools accept an optional account parameter (alias or email). Defaults to the account set in accounts.json.

Commands

/email [action] [account]

Full email management command with actions:

• triage — Summarize inbox, batch archive/trash
• cleanup — 4-phase daily email workflow
• search {query} — Cross-account search
• send / draft / reply — Compose with confirmation

/checkemail [account]

Quick 3-phase inbox sweep:

1. Fetch & classify all inbox emails (auto-archive junk)
2. Batch archive on approval
3. Walk through remaining emails one at a time

Troubleshooting

| Error | Fix | |-------|-----| | accounts.json not found | Copy accounts.example.json to accounts.json | | credentials.json not found | Download OAuth credentials from GCP Console | | No token for... | Run npm run auth -- | | Token refresh failed | Re-authenticate: npm run auth -- | | 403 Forbidden | Add your email as test user in GCP OAuth consent screen | | 403 insufficient scopes | Re-authenticate to get updated scopes |

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: coreyepstein
• Source: coreyepstein/advanced-gmail-mcp
• License: MIT
• Homepage: https://github.com/coreyepstein/advanced-gmail-mcp

Install and usage instructions live in the source repository linked above.