Gmail MCP Server

A comprehensive Model Context Protocol (MCP) server for Gmail, providing 24 tools for full email management including sending, receiving, labels, filters, attachments, and batch operations.

Features

• 24 Gmail Tools: Full email operations, label management, filters, batch operations, and attachments
• Multi-Account Support: Manage multiple Gmail accounts with --account flag
• OAuth Authentication: Secure authentication with automatic token refresh
• Attachment Support: Download and send attachments
• Batch Operations: Efficiently modify or delete up to 1000 emails at once
• Filter Templates: Pre-built filter templates for common use cases
• MCP Resources: Access messages, threads, and labels via URI

Prerequisites

• Node.js 18+
• A Google Cloud Project with Gmail API enabled
• OAuth 2.0 credentials (Desktop app type)

Setup

1. Create Google Cloud OAuth Credentials

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Gmail API:
   • Navigate to "APIs & Services" > "Library"
   • Search for "Gmail API"
   • Click "Enable"
4. Create OAuth credentials:
   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth Client ID"
   • If prompted, configure the OAuth consent screen:
     • Choose "External" user type (or "Internal" for Workspace)
     • Fill in required fields (app name, user support email, developer email)
     • Add scopes: gmail.modify and gmail.settings.basic
     • Add your email as a test user
   • Select "Desktop app" as the application type
   • Name it (e.g., "Gmail MCP")
   • Click "Create"
5. Download the JSON credentials file

2. Install and Configure

# Clone or download the project
cd gmail-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Create config directory and save credentials
mkdir -p ~/.gmail-mcp
cp /path/to/downloaded/credentials.json ~/.gmail-mcp/credentials.json

# Authenticate (for a single account)
node dist/index.js auth

# Or authenticate with a named account (for multi-account support)
node dist/index.js auth --account work
node dist/index.js auth --account personal

The auth command will:

1. Open your browser to Google's OAuth consent page
2. Ask you to authorize the application
3. Save the tokens to ~/.gmail-mcp/tokens/<account>.json

To list authenticated accounts:

node dist/index.js list

3. Add to Claude Code

For a single account:

claude mcp add gmail -- node /path/to/gmail-mcp/dist/index.js

For multiple accounts, add each with its own name:

claude mcp add gmail-work -- node /path/to/gmail-mcp/dist/index.js --account work
claude mcp add gmail-personal -- node /path/to/gmail-mcp/dist/index.js --account personal

Or add manually to your Claude Code MCP settings:

{
  "mcpServers": {
    "gmail-work": {
      "command": "node",
      "args": ["/path/to/gmail-mcp/dist/index.js", "--account", "work"]
    },
    "gmail-personal": {
      "command": "node",
      "args": ["/path/to/gmail-mcp/dist/index.js", "--account", "personal"]
    }
  }
}

Available Tools

Email Operations (7 tools)

Tool	Description
search_emails	Search with Gmail query syntax, pagination
read_email	Full message with headers, body, attachment info
send_email	Send with to/cc/bcc, attachments, threading
draft_email	Create draft without sending
delete_email	Trash or permanent delete
modify_email	Add/remove labels from message
get_thread	Get full conversation thread

Label Management (6 tools)

Tool	Description
list_labels	All labels (system + user)
create_label	Create with color, visibility
update_label	Rename, change settings
delete_label	Remove custom label
get_or_create_label	Idempotent label creation
get_label	Get single label details

Filter Management (5 tools)

Tool	Description
list_filters	All Gmail filters
get_filter	Single filter details
create_filter	Custom criteria + actions
delete_filter	Remove filter
create_filter_from_template	Preset templates

Batch Operations (2 tools)

Tool	Description
batch_modify_emails	Bulk add/remove labels (50 at a time)
batch_delete_emails	Bulk delete with fallback

Attachments (2 tools)

Tool	Description
download_attachment	Save to local filesystem
list_attachments	Get attachment metadata for message

Utilities (2 tools)

Tool	Description
get_profile	User email address, history ID
get_quota	Storage usage info

Resources

Resource	URI Pattern
Message	gmail://messages/{messageId}
Thread	gmail://threads/{threadId}
Label	gmail://labels/{labelId}

Usage Examples

Search for unread emails

Search my Gmail for unread emails from the last week

Read a specific email

Read the email with ID 18abc123def

Send an email

Send an email to john@example.com with subject "Hello" and body "Hi John, how are you?"

Create a filter

Create a Gmail filter that labels all emails from newsletter@example.com with "Newsletters"

Batch operations

Move all emails matching "is:unread older_than:30d" to trash

OAuth Scopes

The server uses these scopes:

• gmail.modify - Read, compose, send, and modify emails and labels
• gmail.settings.basic - Manage mail filters

File Structure

gmail-mcp/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── server.ts             # MCP server setup
│   ├── gmail/
│   │   ├── auth.ts           # OAuth flow
│   │   ├── client.ts         # Gmail API wrapper
│   │   ├── mime.ts           # MIME parsing/encoding
│   │   └── types.ts          # Type definitions
│   ├── tools/
│   │   ├── index.ts          # Tool registration
│   │   ├── emails.ts         # Email operations
│   │   ├── labels.ts         # Label management
│   │   ├── filters.ts        # Filter management
│   │   ├── batch.ts          # Batch operations
│   │   └── attachments.ts    # Attachment handling
│   ├── resources/
│   │   └── index.ts          # MCP resources
│   └── schemas/
│       └── index.ts          # Zod schemas
├── package.json
├── tsconfig.json
└── README.md

Security

• Credentials stored in ~/.gmail-mcp/ with restricted permissions (0600)
• Per-account tokens stored in ~/.gmail-mcp/tokens/
• Tokens automatically refresh when expired
• OAuth callback only on localhost
• No external telemetry or data collection

Troubleshooting

"Not authenticated" error

Run node dist/index.js auth --account <name> to authenticate.

"Permission denied" error

Ensure your OAuth credentials have the correct scopes and the Gmail API is enabled.

Token refresh fails

Delete ~/.gmail-mcp/tokens/<account>.json and run auth again.

Port 3000 in use

The OAuth callback requires port 3000. Close any applications using this port.

License

MIT