gmail-mcp

gmail-mcp

A Model Context Protocol (MCP) server that exposes Gmail actions as tools, allowing AI assistants like Claude to send, read, list, and reply to emails on your behalf.

Tools

| Tool | Description | |------|-------------| | send_email | Send an email to a recipient | | list_emails | List emails matching a Gmail search query | | read_email | Read a specific email by message ID | | read_emails_from_sender | Fetch recent emails from a specific sender | | reply_email | Reply to an email, preserving thread headers | | forward_recent_replies_to_webhook | Forward recent Gmail replies to a signed LeadBorg email webhook |

Requirements

• Python 3.13+
• A Google Cloud project with the Gmail API enabled
• OAuth 2.0 credentials (google_creds.json)

Setup

1. Get Google OAuth credentials

1. Go to the Google Cloud Console.
2. Create a project (or select an existing one).
3. Enable the Gmail API.
4. Under APIs & Services > Credentials, create an OAuth 2.0 Client ID (Application type: Desktop app).
5. Download the JSON file and save it as google_creds.json in the project root.

2. Install dependencies

# Using uv (recommended)
uv sync

# Or pip
pip install -e .

3. Authenticate

Run the server once manually to trigger the OAuth browser flow:

python gmail_mcp.py

This creates a token.json file at ~/.config/gmail-mcp/token.json. Subsequent runs reuse and auto-refresh this token.

Running the server

The transport is controlled by the MCP_TRANSPORT environment variable (default: stdio).

stdio (default — for Claude Desktop / MCP clients)

python gmail_mcp.py

Streamable HTTP

MCP_TRANSPORT=streamable-http MCP_PORT=8001 python gmail_mcp.py
# or alias:
MCP_TRANSPORT=http python gmail_mcp.py

SSE

MCP_TRANSPORT=sse python gmail_mcp.py

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | MCP_TRANSPORT | stdio | Transport mode: stdio, sse, streamable-http (alias: http) | | MCP_HOST | 127.0.0.1 | Host for HTTP/SSE transports | | MCP_PORT | 8001 | Port for HTTP/SSE transports | | GOOGLE_CREDS_PATH | ~/.config/gmail-mcp/google_creds.json | Path to OAuth client credentials file | | GOOGLE_TOKEN_PATH | ~/.config/gmail-mcp/token.json | Path to cached OAuth token file |

Claude Desktop configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["/absolute/path/to/gmail_mcp.py"]
    }
  }
}

Running tests

python -m pytest tests/
# or
python -m unittest discover tests/

Project structure

gmail-mcp/
├── gmail_mcp.py        # MCP server and tool definitions
├── main.py             # Alternate entry point (HTTP transport)
├── pyproject.toml
└── tests/
    └── test_gmail_mcp.py

~/.config/gmail-mcp/
├── google_creds.json   # OAuth client credentials (not committed)
└── token.json          # Cached OAuth token (generated at runtime)

Permissions

The server requests two OAuth scopes:

• https://www.googleapis.com/auth/gmail.readonly — read access to emails
• https://www.googleapis.com/auth/gmail.send — permission to send email

This does not grant access to delete messages permanently.

LeadBorg integration notes

When using this server from LeadBorg, configure the email MCP endpoint as:

http://localhost:8001/mcp/

Set the provider to gmail-mcp. LeadBorg will pass a signed reply_to alias to send_email; Gmail-MCP writes it as the Reply-To header so inbound replies can be correlated back to the lead.

For local reply ingestion, run the forward_recent_replies_to_webhook tool with the LeadBorg webhook URL (/api/webhooks/email/mcp) and the same signing secret configured as EMAIL_WEBHOOK_SIGNING_SECRET.