Gmail MCP Server

Model Context Protocol (MCP) server for Gmail API integration. Provides 17 tools for email management, labels, threads, attachments, and drafts.

Features

Email Operations (7 tools)

• gmail_search_messages - Search using Gmail query syntax (from:, to:, subject:, is:unread)

• gmail_get_message - Get full message content with headers and body

• gmail_send_message - Send email with to/cc/bcc recipients

• gmail_delete_message - Permanently delete message (bypass trash)

• gmail_trash_message - Move to trash (reversible)

• gmail_untrash_message - Restore from trash

• gmail_modify_message_labels - Add/remove labels from message

Labels (3 tools)

• gmail_list_labels - List all labels with IDs and types

• gmail_create_label - Create new custom label

• gmail_delete_label - Remove custom label

Threads (3 tools)

• gmail_list_threads - List conversation threads

• gmail_get_thread - Get full thread with all messages

• gmail_modify_thread_labels - Apply/remove labels from entire thread

Attachments (1 tool)

• gmail_get_attachment - Download attachment data

Drafts (3 tools)

• gmail_list_drafts - List draft messages

• gmail_create_draft - Create new draft

• gmail_send_draft - Send existing draft

Installation

1. Install Dependencies

2. Google Cloud Console Setup

1. Go to Google Cloud Console

2. Create a new project or select existing project

3. Enable the Gmail API:

   • Navigate to "APIs & Services" > "Library"

   • Search for "Gmail API"

   • Click "Enable"

4. Create OAuth 2.0 credentials:

   • Navigate to "APIs & Services" > "Credentials"

   • Click "Create Credentials" > "OAuth client ID"

   • Application type: "Desktop app"

   • Name: "Gmail MCP Server"

   • Click "Create"

5. Download credentials as credentials.json

3. Initial OAuth Flow

Run the initial OAuth flow to obtain a refresh token:

This will:

• Open a browser for Google OAuth consent

• Request gmail.modify scope

• Save refresh token to display

Copy the refresh token for the next step.

4. Store Credentials in OpenBao

Store the OAuth credentials in OpenBao:

Secret Path Pattern: secret/{client}/{env}-mcp-gmail-{username}

• Example: secret/client0/prod-mcp-gmail-samuel

• Username is auto-detected from git config user.email

5. Test the Server

6. Deploy to mcp-proxy

Add to ~/.claude/mcp-proxy/config.json:

Then run structure_generator to create hierarchy files:

Development Mode

For local development without OpenBao:

OAuth Scopes

This server requires the gmail.modify scope:

• https://www.googleapis.com/auth/gmail.modify

This provides full mailbox access including:

• Read messages and threads

• Send messages

• Modify labels

• Delete messages

• Manage drafts

Security

• Never commit credentials.json or tokens to git

• OAuth refresh tokens are stored securely in OpenBao

• Access tokens are refreshed automatically on each request

• All API communication uses HTTPS

Troubleshooting

"OPENBAO_ERROR: Agent not running"

Start the OpenBao agent:

"Failed to refresh OAuth token"

The refresh token may be invalid or expired. Run python oauth_setup.py again to generate a new one.

"Permission denied" errors

Ensure the OAuth consent screen includes the gmail.modify scope. You may need to re-authorize.

Rate Limiting

Gmail API has these limits:

• 1 billion quota units per day

• 250 quota units per user per second

• Batch requests: 100 requests per batch

The server handles rate limit errors automatically with retry suggestions.

Sources

Gmail API Documentation:

• Gmail API Reference

• Python Quickstart

• OAuth 2.0 for Google APIs

MCP Documentation:

• Model Context Protocol

• MCP Python SDK