Gmail MCP Server

A secure, production-ready Model Context Protocol server that gives Claude full Gmail integration — reading, searching, sending, replying, forwarding, managing labels, and more.

v2.0 — This release resolves all security findings from the audit:
encrypted token storage, CSRF protection, confirmation guards on destructive operations,
HTML sanitisation, attachment size caps, rate-limit backoff, and minimal OAuth scopes.

Features

| Category | Tools | |----------|-------| | Read | list_emails, read_email, search_emails, get_attachments, download_attachment | | Write | send_email, reply_to_email, forward_email, save_draft | | Manage | delete_email, move_email, mark_email, create_label, delete_label, list_labels, batch_delete, empty_trash | | Health | ping |

Prerequisites

Node.js 20+ (LTS recommended)
A Google Cloud Console project with the Gmail API enabled
OAuth 2.0 Desktop application credentials (credentials.json)

Google Cloud Console Setup

Go to Google Cloud Console
Create a new project (or select an existing one)
Navigate to APIs & Services → Library and enable the Gmail API
Go to APIs & Services → Credentials → Create Credentials → OAuth client ID
- Application type: Desktop app
- Name: Gmail MCP Server (or any name)
Download the credentials JSON file — save it as credentials.json in the project root
Go to APIs & Services → OAuth consent screen
- Add your Google account as a Test user (required while the app is in testing mode)

Required OAuth Scopes

The server requests these minimal scopes (not the full https://mail.google.com/):

| Scope | Used for | |-------|----------| | gmail.readonly | list_emails, read_email, search_emails, get_attachments | | gmail.send | send_email, reply_to_email, forward_email | | gmail.compose | save_draft | | gmail.modify | move_email, mark_email, delete_email, create_label, delete_label, batch_delete, empty_trash |

Installation

git clone https://github.com/yourusername/gmail-mcp-server.git
cd gmail-mcp-server
npm install
npm run build

Configuration

1. Generate an encryption key

The server encrypts your OAuth tokens at rest using AES-256-GCM. Generate a 32-byte key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Save the output — you will need it in every environment where the server runs.
If you lose the key, you must delete the token file and re-authenticate.

2. Set environment variables

# Required — 64 hex characters (32 bytes)
export GMAIL_MCP_TOKEN_KEY="your-64-char-hex-key-here"

# Optional
export GMAIL_MCP_LOG_LEVEL="info"          # debug | info | warn | error
export GMAIL_MCP_CONCURRENCY="5"           # parallel API fetch limit
export GMAIL_MCP_MAX_ATTACHMENT_BYTES="5242880"  # 5 MB inline attachment cap
export GMAIL_MCP_MAX_BODY_BYTES="5242880"        # 5 MB email body cap
export GMAIL_MCP_CONFIG_DIR="$HOME/.config/gmail-mcp"  # token storage dir
export GMAIL_MCP_CREDENTIALS_PATH="./credentials.json"  # credentials location
export GMAIL_MCP_REDIRECT_PORT="3000"      # OAuth callback port

Claude Desktop Configuration

Add the following to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-mcp-server/dist/index.js"],
      "env": {
        "GMAIL_MCP_TOKEN_KEY": "your-64-char-hex-key-here",
        "GMAIL_MCP_LOG_LEVEL": "info",
        "GMAIL_MCP_CREDENTIALS_PATH": "/absolute/path/to/credentials.json"
      }
    }
  }
}

Important: Use absolute paths. Claude Desktop may not inherit your shell's PATH or working directory.

First-Time Authentication

On first launch, the server will print an authorization URL to its log output (stderr).
Open it in your browser, sign in with your Google account, and grant the requested permissions.

The server will automatically:

Complete the OAuth callback (on http://localhost:3000/oauth2callback)
Exchange the authorization code for tokens
Encrypt and save the tokens to ~/.config/gmail-mcp/token.enc

Subsequent launches will use the saved (encrypted) tokens and refresh them automatically.

To view the authorization URL when running through Claude Desktop, check the MCP server logs.

Security

| Feature | Implementation | |---------|---------------| | Token encryption | AES-256-GCM, key from environment variable | | Token file permissions | 0o600 (owner read/write only) | | CSRF protection | 16-byte random state parameter verified on OAuth callback | | Minimal OAuth scopes | Four granular scopes instead of full https://mail.google.com/ | | HTML sanitisation | sanitize-html with strict allowlist before sending/drafting | | Destructive operation guards | permanent:true and empty_trash require confirmed:true | | Attachment size cap | Returns metadata-only above 5 MB; use download_attachment for individual files | | Body size cap | Emails and drafts capped at 5 MB at schema validation level | | Rate-limit backoff | Exponential backoff with jitter on 429/5xx responses | | Concurrent fetch limit | Configurable semaphore (default: 5 parallel requests) | | Token refresh mutex | Single refresh-at-a-time to prevent invalid_grant race condition | | Safe error messages | Raw API errors logged to stderr only; LLM receives whitelisted messages | | From: header | Always populated from authenticated user's profile | | BCC in reply-all | Filtered by actual email address; BCC never exposed to CC recipients | | Subject deduplication | Re: and Fwd: prefixes stripped before re-prepending |

Tool Reference

`ping`

Health check. Returns server version, authenticated user, token expiry, and mailbox stats.

`list_emails`

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | folder | string | "INBOX" | Gmail label ID (e.g. "INBOX", "SENT", "Label_42") | | maxResults | number | 20 | 1–500 | | query | string | — | Gmail search query to filter results | | pageToken | string | — | Pagination token from previous response |

`read_email`

| Parameter | Type | Description | |-----------|------|-------------| | emailId | string | Gmail message ID |

`search_emails`

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | string | required | Gmail search syntax (e.g. "from:alice is:unread") | | maxResults | number | 20 | 1–500 | | pageToken | string | — | Pagination token |

`get_attachments`

| Parameter | Type | Description | |-----------|------|-------------| | emailId | string | Gmail message ID |

Returns inline base64 data if total size ≤ 5 MB; metadata-only otherwise.
Use download_attachment for individual files above the cap.

`download_attachment`

| Parameter | Type | Description | |-----------|------|-------------| | emailId | string | Gmail message ID | | attachmentId | string | Attachment ID (from get_attachments response) |

`send_email`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | to | string | ✅ | Recipient(s), comma-separated | | cc | string | — | CC recipients | | bcc | string | — | BCC recipients | | subject | string | ✅ | Subject line | | body | string | ✅ | Email body (max 5 MB) | | isHtml | boolean | — | Set true for HTML email (sanitised) |

`reply_to_email`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | emailId | string | ✅ | ID of email to reply to | | threadId | string | ✅ | Thread ID | | body | string | ✅ | Reply body (max 5 MB) | | isHtml | boolean | — | HTML reply | | replyAll | boolean | — | Include all CC recipients |

`forward_email`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | emailId | string | ✅ | ID of email to forward | | to | string | ✅ | Forward-to address(es) | | additionalMessage | string | — | Text/HTML prepended before forwarded content | | isHtml | boolean | — | HTML format |

`save_draft`

All fields optional except body (default: empty string).

`delete_email`

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | emailId | string | required | Gmail message ID | | permanent | boolean | false | If true, permanently delete (irreversible) | | confirmed | boolean | — | Required when permanent:true |

`move_email`

| Parameter | Type | Description | |-----------|------|-------------| | emailId | string | Gmail message ID | | targetLabel | string | Destination label ID |

`mark_email`

| Parameter | Type | Description | |-----------|------|-------------| | emailId | string | Gmail message ID | | action | enum | read | unread | star | unstar | important | unimportant |

`create_label`

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | name | string | required | Label name | | visibility | enum | "show" | show | hide | showIfUnread |

`delete_label`

| Parameter | Type | Description | |-----------|------|-------------| | labelId | string | Label ID (system labels cannot be deleted) |

`list_labels`

No parameters. Returns systemLabels and userLabels arrays with message counts.

`batch_delete`

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | emailIds | string[] | required | 1–1000 message IDs | | permanent | boolean | false | Permanent delete if true (requires confirmed:true) | | confirmed | boolean | — | Required when permanent:true |

Returns { succeeded: string[], failed: Array<{id, reason}> }.

`empty_trash`

| Parameter | Type | Description | |-----------|------|-------------| | confirmed | true | Must be literal true — permanently deletes all Trash messages |

Returns { deletedCount: number }.

Development

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build TypeScript
npm run build

# Start server directly (after building)
npm start

Token Rotation

OAuth refresh tokens do not expire unless revoked, but periodic rotation is good practice.

# 1. Delete the encrypted token file
rm ~/.config/gmail-mcp/token.enc

# 2. Restart Claude Desktop (or the MCP server)
#    You will be prompted to re-authorize in your browser.

# 3. Revoke the old token (optional but recommended)
#    https://myaccount.google.com/permissions

Logs

All server logs are written to stderr as structured JSON (never stdout, which is reserved for the MCP protocol). To capture logs when running through Claude Desktop, check the MCP server log files:

macOS: ~/Library/Logs/Claude/mcp-server-gmail.log

Log levels: debug, info, warn, error — controlled by GMAIL_MCP_LOG_LEVEL.

Troubleshooting

| Symptom | Likely cause | Fix | |---------|-------------|-----| | GMAIL_MCP_TOKEN_KEY must be set | Missing env var | Set the 64-char hex key | | credentials.json not found | Wrong path | Set GMAIL_MCP_CREDENTIALS_PATH | | Authentication failed | Expired/revoked token | Delete token.enc and re-authenticate | | Permission denied | Wrong OAuth scope | Re-authenticate (scopes changed) | | OAuth state mismatch | Stale browser tab | Restart the auth flow | | Conflict — resource exists | Duplicate label name | Choose a different label name |

License

MIT

MCP Servers

Gmail MCP Server

Features

Prerequisites

Google Cloud Console Setup

Required OAuth Scopes

Installation

Configuration

1. Generate an encryption key

2. Set environment variables

Claude Desktop Configuration

First-Time Authentication

Security

Tool Reference

`ping`

`list_emails`

`read_email`

`search_emails`

`get_attachments`

`download_attachment`

`send_email`

`reply_to_email`

`forward_email`

`save_draft`

`delete_email`

`move_email`

`mark_email`

`create_label`

`delete_label`

`list_labels`

`batch_delete`

`empty_trash`

Development

Token Rotation

Logs

Troubleshooting

License

安装包（如果需要）

Cursor 配置 (mcp.json)

Gmail MCP Server

Features

Prerequisites

Google Cloud Console Setup

Required OAuth Scopes

Installation

Configuration

1. Generate an encryption key

2. Set environment variables

Claude Desktop Configuration

First-Time Authentication

Security

Tool Reference

ping

list_emails

read_email

search_emails

get_attachments

download_attachment

send_email

reply_to_email

forward_email

save_draft

delete_email

move_email

mark_email

create_label

delete_label

list_labels

batch_delete

empty_trash

Development

Token Rotation

Logs

Troubleshooting

License

安装包 （如果需要）

Cursor 配置 (mcp.json)

`ping`

`list_emails`

`read_email`

`search_emails`

`get_attachments`

`download_attachment`

`send_email`

`reply_to_email`

`forward_email`

`save_draft`

`delete_email`

`move_email`

`mark_email`

`create_label`

`delete_label`

`list_labels`

`batch_delete`

`empty_trash`

安装包（如果需要）