Gmail MCP

# GMAIL-MCP A Dedalus MCP server for **read-only** access to the Gmail API v1. ## Setup ### 1) Dedalus credentials (required) This server uses the Dedalus MCP framework and expects your Dedalus credentials to be available as environment variables (for the MCP auth handshake). ### 2) Google Cloud setup (one-time) - Go to the [Google Cloud Console](https://console.cloud.google.com) - Create/select a project - Enable **Gmail API** - Configure **OAuth consent screen** - If in testing mode: add your Google account as a **Test user** - Create **OAuth client ID** - Application type: **Desktop app** - Download the JSON (OAuth client credentials) ### 3) Configure environment Copy `.env.example` to `.env` and set your OAuth client JSON path: ```text GOOGLE_OAUTH_CREDENTIALS=/absolute/path/to/your/oauth-client.json ``` ### 4) Install dependencies ```bash uv sync ``` ### 5) Authenticate once (opens browser and stores tokens) ```bash uv run python -m src.gmail_auth ``` Tokens will be stored at `~/.config/gmail-mcp/tokens.json` by default. ### 6) Run the server ```bash uv run python -m src.main ``` ## Available Tools (Read-only) - `gmail_get_profile` - Get Gmail profile - `gmail_list_labels` - List labels - `gmail_list_messages` - List/search messages (supports Gmail query operators) - `gmail_get_message` - Get a message by ID - `gmail_get_thread` - Get a thread by ID - `gmail_get_attachment` - Download an attachment by ID ## Authentication ### Google OAuth (recommended) - Set `GOOGLE_OAUTH_CREDENTIALS` - Run `uv run python -m src.gmail_auth` - `gmail-mcp` will auto-refresh access tokens when possible. Default scope: - `https://www.googleapis.com/auth/gmail.readonly` ### Environment variables - `GOOGLE_OAUTH_CREDENTIALS`: Path to downloaded OAuth client JSON (**Desktop app**) - `GMAIL_TOKEN_PATH` (optional): Token file location (default `~/.config/gmail-mcp/tokens.json`) - `GMAIL_SCOPES` (optional): Comma-separated scopes (default is read-only) - `GMAIL_ACCESS_TOKEN` (optional/manual): If set, overrides all other auth logic ## License MIT