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

cd ~/repos/3-resources/MCP/mcp-proxy/gmail-mcp
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

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:

python3 oauth_setup.py

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:

# Ensure OpenBao agent is running
start-openbao-mcp

# Store credentials (replace values with your actual credentials)
bao kv put secret/client0/prod-mcp-gmail-$(git config user.email | cut -d'@' -f1) \
  client_id="YOUR_CLIENT_ID.apps.googleusercontent.com" \
  client_secret="YOUR_CLIENT_SECRET" \
  refresh_token="YOUR_REFRESH_TOKEN"

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

# Test server startup
python gmail_mcp.py
# Should print "MCP_SERVER_READY" to stderr

# Test with MCP Inspector (in separate terminal)
npx @modelcontextprotocol/inspector python gmail_mcp.py

6. Deploy to mcp-proxy

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

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["/home/samuel/repos/3-resources/MCP/mcp-proxy/gmail-mcp/gmail_mcp.py"],
      "env": {}
    }
  }
}

Then run structure_generator to create hierarchy files:

cd ~/repos/3-resources/MCP/mcp-proxy
./structure_generator.py

Development Mode

For local development without OpenBao:

export OPENBAO_DEV_MODE=1
export GMAIL_CLIENT_ID="your-client-id"
export GMAIL_CLIENT_SECRET="your-client-secret"
export GMAIL_REFRESH_TOKEN="your-refresh-token"

python gmail_mcp.py

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:

export BW_SESSION=$(bw unlock --raw)
start-openbao-mcp

"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