Gmail-MCP

# Gmail-MCP An [MCP](https://modelcontextprotocol.io) 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](https://docs.astral.sh/uv/). 1. **Create a Google OAuth client.** In [Google Cloud Console](https://console.cloud.google.com/), enable the Gmail API and create an OAuth 2.0 **Desktop app** client. Download the JSON. 2. **Place the credentials.** Save the JSON to `~/.config/gmail-mcp/gmail_credentials.json`, or point `GMAIL_CREDENTIALS_PATH` at it. 3. **Install dependencies.** ```bash uv sync ``` 4. **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`). ```bash 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 ```bash # 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 ```json { "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](LICENSE).