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

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

Command	Description
npx gmail-mcp-server auth	Open the browser dashboard (add or manage accounts)
npx gmail-mcp-server list-accounts	List all connected accounts
npx gmail-mcp-server remove-account <email>	Remove an account and delete its token

Tools Reference

Email Messages

Tool	Description
gmail_list_emails	List emails with optional query/label filtering and pagination
gmail_get_email	Get full email content including body, HTML, and attachment metadata
gmail_send_email	Send a new email (supports HTML, CC, BCC)
gmail_reply_to_email	Reply to an email with proper threading headers
gmail_forward_email	Forward an email with optional message prefix
gmail_trash_email	Move an email to trash
gmail_delete_email	Permanently delete an email (requires confirmDelete: true)
gmail_mark_as_read	Remove the UNREAD label from a message
gmail_mark_as_unread	Add the UNREAD label to a message
gmail_archive_email	Remove from inbox (remove INBOX label)
gmail_star_email	Add STARRED label to a message
gmail_batch_modify	Add/remove labels from multiple messages at once

Drafts

Tool	Description
gmail_create_draft	Create a new draft email
gmail_list_drafts	List all drafts with subject and snippet
gmail_get_draft	Get full draft content
gmail_update_draft	Update an existing draft
gmail_delete_draft	Delete a draft
gmail_send_draft	Send an existing draft

Labels

Tool	Description
gmail_list_labels	List all labels with counts
gmail_create_label	Create a label with optional color
gmail_update_label	Update label name, visibility, or color
gmail_delete_label	Delete a label
gmail_add_label_to_email	Apply a label to a message
gmail_remove_label_from_email	Remove a label from a message

Search & Threads

Tool	Description
gmail_search	Search emails using full Gmail search syntax
gmail_get_thread	Get all messages in a thread in order
gmail_list_threads	List threads with optional query filtering

Attachments

Tool	Description
gmail_list_attachments	List all attachments in an email
gmail_get_attachment	Download attachment as base64 or save to disk

Settings

Tool	Description
gmail_get_vacation_responder	Get vacation/out-of-office settings
gmail_set_vacation_responder	Configure vacation auto-reply
gmail_disable_vacation_responder	Turn off auto-reply
gmail_list_filters	List all email filters
gmail_create_filter	Create a new email filter with actions
gmail_delete_filter	Delete an email filter

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

Variable	Required	Description
GMAIL_ACCOUNT	Only with multiple accounts	Email address of the account to use

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