Gmail-MCP

An MCP server that exposes Gmail over the Model Context Protocol, so an MCP-aware client (Omnexus, Claude Desktop, Claude Code, etc.) can search threads, read messages, manage labels, and draft replies on your behalf.

Tools

| Tool | Purpose | | --- | --- | | search_threads | Search threads with Gmail's query syntax (from:alice newer_than:7d, ...). | | get_thread | Fetch a thread's subject, participants, and per-message bodies. | | list_labels | List all system + user labels with their IDs. | | get_label_id | Resolve a label name to its ID (case-insensitive). | | add_thread_label / remove_thread_label | Apply or remove labels on a thread. | | create_draft | Save a draft (does not send). |

OAuth scopes requested: gmail.readonly, gmail.compose, gmail.labels, gmail.modify. Sending mail is intentionally not authorized.

Setup

Requires Python 3.14 and uv.

Create a Google OAuth client. In Google Cloud Console, enable the Gmail API and create an OAuth 2.0 Desktop app client. Download the JSON.
Place the credentials. Save the JSON to ~/.config/gmail-mcp/gmail_credentials.json, or point GMAIL_CREDENTIALS_PATH at it.
Install dependencies.
```
uv sync
```
Authorize once. This opens a browser, completes the OAuth flow, and caches a refresh token at ~/.config/gmail-mcp/gmail_token.json (override with GMAIL_TOKEN_PATH).
```
uv run server.py --gmail-auth
```
Run this before wiring the server into an MCP client — under stdio transport the browser handshake will hang the client.

Running

# stdio (default; what most MCP clients expect)
uv run server.py

# streamable HTTP
uv run server.py --transport streamable-http --host 127.0.0.1 --port 8000

Claude Desktop / Claude Code config

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": ["--directory", "/path/to/Gmail-MCP", "run", "server.py"]
    }
  }
}

Environment variables

| Variable | Default | Purpose | | --- | --- | --- | | GMAIL_CREDENTIALS_PATH | ~/.config/gmail-mcp/gmail_credentials.json | OAuth client config from Google Cloud Console. | | GMAIL_TOKEN_PATH | ~/.config/gmail-mcp/gmail_token.json | Cached user token (created on first auth, refreshed automatically). |

A .env file in the project root is loaded on startup.

License

See LICENSE.

MCP Servers