Gmail MCP Server

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)

Label Management (6 tools)

Filter Management (5 tools)

Batch Operations (2 tools)

Attachments (2 tools)

Utilities (2 tools)

Resources