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

Go to Google Cloud Console
Create a new project or select an existing one
Enable the Gmail API:
- Navigate to "APIs & Services" > "Library"
- Search for "Gmail API"
- Click "Enable"
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"
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:

Open your browser to Google's OAuth consent page
Ask you to authorize the application
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

gmail-mcp