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

Related MCP server: Artificial Virtual Assistant (AVA)

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

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