gmail-mcp-server

A production-ready MCP (Model Context Protocol) server that connects Claude AI to your Gmail account, enabling full email management through natural language.

No Google Cloud setup knowledge required — just add it to Claude Desktop and follow the on-screen instructions.

Features

• Email Management — list, read, send, reply, forward, trash, delete, archive, star emails

• Drafts — create, list, read, update, delete, and send drafts

• Labels — create, list, update, delete labels; add/remove labels from messages

• Search — full Gmail search syntax, thread retrieval, pagination

• Attachments — list and download attachments, optionally save to disk

• Settings — vacation responder management, email filter creation and deletion

• Batch Operations — apply label changes to multiple emails at once

• Multi-Account — connect multiple Gmail accounts; switch with one env var

• Auto Token Refresh — OAuth tokens refreshed and persisted automatically

• Guided Browser Setup — first-time setup opens a UI in your browser automatically

• Account Dashboard — manage connected accounts, view token status, and get your Claude Desktop config in one place

Related MCP server: mcp-gmail

Setup

1. Add to Claude Desktop

Open your Claude Desktop config file:

• macOS/Linux: ~/.config/claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this entry and restart Claude Desktop:

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

2. Connect Your Gmail

Ask Claude anything Gmail-related:

"Check my Gmail"

A browser setup page opens automatically. Follow the on-screen steps to connect your Gmail account — takes about 2 minutes. You only do this once.

After signing in, you'll be taken to the account dashboard where you can:

• See all connected accounts and their token status

• Remove accounts with one click

• Copy a ready-made Claude Desktop config snippet

Multiple Accounts

From the dashboard, click Add Another Account, or run:

npx gmail-mcp-server auth

Then add each account as a separate entry in Claude Desktop config using the GMAIL_ACCOUNT env var:

{
  "mcpServers": {
    "gmail-personal": {
      "command": "npx",
      "args": ["-y", "gmail-mcp-server"],
      "env": { "GMAIL_ACCOUNT": "personal@gmail.com" }
    },
    "gmail-work": {
      "command": "npx",
      "args": ["-y", "gmail-mcp-server"],
      "env": { "GMAIL_ACCOUNT": "work@company.com" }
    }
  }
}

If only one account is connected, GMAIL_ACCOUNT is optional — the server uses it automatically.

CLI Commands

Tools Reference

Email Messages

Drafts

Labels

Search & Threads

Attachments

Settings

Gmail Search Syntax Examples

Ask Claude using Gmail's full search syntax:

# Unread emails from a specific sender
from:boss@example.com is:unread

# Emails with attachments in the last week
has:attachment newer_than:7d

# Large emails over 10MB
larger:10m

# Emails in specific labels
label:work label:urgent

# Starred unread emails
is:starred is:unread

Environment Variables

Token Storage

Credentials and tokens are stored locally at ~/.gmail-mcp/:

~/.gmail-mcp/
├── config.json        ← Google OAuth client credentials
├── accounts.json      ← Registered Gmail accounts
└── tokens/
    ├── personal@gmail.com.json
    └── work@company.com.json

These files never leave your machine. To revoke access, run remove-account or revoke the app at myaccount.google.com/permissions.

Troubleshooting

Setup page opens but credentials form fails

Make sure you created a Desktop App OAuth client in Google Cloud Console, not a Web App. Web App clients reject localhost redirect URIs unless explicitly allowlisted.

"Multiple accounts found. Set GMAIL_ACCOUNT env var"

Add "GMAIL_ACCOUNT": "your@email.com" to the env section of the relevant Claude Desktop config entry.

Auth expired / 401 error

Re-run auth for that account:

npx gmail-mcp-server remove-account your@email.com
npx gmail-mcp-server auth

"Insufficient permissions" / 403 error

The token was created without all required scopes. Remove and re-authenticate:

npx gmail-mcp-server remove-account your@email.com
npx gmail-mcp-server auth

Gmail rate limit hit / 429 error

Gmail API rate limit reached. Wait 1-2 minutes and retry.

Contributing

See CONTRIBUTING.md for development setup and PR guidelines.

License

MIT — see LICENSE