Gmail MCP Server

# Gmail MCP Server A Model Context Protocol (MCP) server for Gmail that provides natural language interaction with your inbox, daily summaries organized by category, and Home Assistant integration. ## Features - 🔍 **Natural Language Search** - Search emails using plain language or Gmail query syntax - 📊 **Category-Based Summaries** - Automatic categorization: Navy, Kids, Financial, Action Items - 📱 **Home Assistant Integration** - REST API with sensors and notifications support - 🐳 **Docker Support** - Easy deployment with Docker Compose - 🔒 **Read-Only** - Currently read-only access to your inbox (safe!) ## Quick Start ### 1. Google Cloud Setup 1. Go to [Google Cloud Console](https://console.cloud.google.com/) 2. Create a new project or select existing 3. Enable the **Gmail API**: - Navigate to "APIs & Services" → "Enable APIs" - Search for "Gmail API" and enable it 4. Create OAuth credentials: - Go to "APIs & Services" → "Credentials" - Click "Create Credentials" → "OAuth client ID" - Choose "Web application" (or "Desktop app") - For Web application, add `http://localhost:8080` to **Authorized redirect URIs** - Copy the Client ID and Client Secret ### 2. Configuration ```bash # Clone and enter directory cd mcp_gmail # Copy example environment file cp .env.example .env # Edit .env with your credentials # GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com # GOOGLE_CLIENT_SECRET=your-client-secret ``` ### 3. Initial Authentication (OAuth) For the first-time setup, you need to authenticate with Google: ```bash # Run the auth setup container docker compose --profile setup run --rm gmail-mcp-auth ``` This will: 1. Open a browser window for Google authentication 2. Request permission to read your Gmail 3. Save the OAuth token to `./credentials/token.json` ### 4. Start the Server ```bash # Start the main server docker compose up -d # Check logs docker compose logs -f gmail-mcp ``` The REST API will be available at `http://localhost:8000` ## API Endpoints ### Health & Status | Endpoint | Description | |----------|-------------| | `GET /health` | Health check with auth status | | `GET /api/stats` | Inbox statistics | ### Email Data (for Home Assistant Sensors) | Endpoint | Description | |----------|-------------| | `GET /api/unread` | Total unread count | | `GET /api/unread/categories` | Unread count per category | ### Summaries | Endpoint | Description | |----------|-------------| | `GET /api/summary/daily` | Full daily summary (JSON) | | `GET /api/summary/daily/text` | Daily summary as text | | `GET /api/summary/category/{category}` | Category-specific summary | ### Home Assistant Integration | Endpoint | Description | |----------|-------------| | `POST /api/webhook/trigger` | Send summary to HA webhook | ## Home Assistant Configuration ### REST Sensors Add to your `configuration.yaml`: ```yaml sensor: - platform: rest name: Gmail Unread resource: http://gmail-mcp:8000/api/unread value_template: "{{ value_json.unread }}" scan_interval: 300 json_attributes: - timestamp - platform: rest name: Gmail Categories resource: http://gmail-mcp:8000/api/unread/categories value_template: "{{ value_json.total }}" scan_interval: 300 json_attributes: - navy - kids - financial - action_required - other ``` ### Template Sensors (from attributes) ```yaml template: - sensor: - name: "Gmail Navy Unread" state: "{{ state_attr('sensor.gmail_categories', 'navy') }}" icon: mdi:anchor - name: "Gmail Kids Unread" state: "{{ state_attr('sensor.gmail_categories', 'kids') }}" icon: mdi:human-child - name: "Gmail Financial Unread" state: "{{ state_attr('sensor.gmail_categories', 'financial') }}" icon: mdi:currency-usd - name: "Gmail Action Required" state: "{{ state_attr('sensor.gmail_categories', 'action_required') }}" icon: mdi:alert-circle ``` ### Automation: Daily Summary Notification ```yaml automation: - alias: "Daily Email Summary" trigger: - platform: time at: "07:00:00" action: - service: rest_command.gmail_summary - service: notify.mobile_app data: title: "📧 Email Summary" message: "{{ states('sensor.gmail_summary_text') }}" rest_command: gmail_summary: url: "http://gmail-mcp:8000/api/webhook/trigger" method: POST ``` ### Webhook Integration Configure in your `.env`: ```bash HA_WEBHOOK_URL=http://homeassistant.local:8123/api/webhook/gmail_summary HA_LONG_LIVED_TOKEN=your-long-lived-access-token ``` Then create an automation triggered by the webhook: ```yaml automation: - alias: "Gmail Webhook Handler" trigger: - platform: webhook webhook_id: gmail_summary action: - service: notify.mobile_app data: title: "📧 {{ trigger.json.event_type }}" message: "{{ trigger.json.data.text_summary }}" ``` ## MCP Server Usage The MCP server can be used with Claude Desktop or other MCP clients. ### Claude Desktop Configuration Add to your Claude Desktop config (`claude_desktop_config.json`): ```json { "mcpServers": { "gmail": { "command": "docker", "args": [ "exec", "-i", "gmail-mcp-server", "python", "-m", "mcp_gmail.server" ] } } } ``` ### Available MCP Tools | Tool | Description | |------|-------------| | `gmail_search` | Search emails with query | | `gmail_list_unread` | List unread emails by category | | `gmail_get_email` | Get full email content | | `gmail_daily_summary` | Generate categorized summary | | `gmail_category_summary` | Summary for one category | | `gmail_inbox_stats` | Current inbox statistics | | `gmail_get_labels` | List Gmail labels | | `gmail_get_categories` | Show configured categories | ### Example Queries - "What unread emails do I have about Navy?" - "Show me my daily email summary" - "Are there any action items I need to handle?" - "Search for emails from the school" - "What financial emails came in this week?" ## Customizing Categories Edit `config/categories.yaml` to customize email categorization: ```yaml categories: navy: name: "Navy / Military" priority: high matchers: senders: - "@navy.mil" - "@mail.mil" subjects: - "orders" - "deployment" labels: - "Navy" ``` ### Matcher Types - **senders**: Partial match on sender email/name - **subjects**: Partial match on subject line - **labels**: Exact match on Gmail labels ## Development ### Local Setup (without Docker) ```bash # Create virtual environment python -m venv venv source venv/bin/activate # or `venv\Scripts\activate` on Windows # Install in development mode pip install -e ".[dev]" # Run authentication mcp-gmail-auth # Run the API server mcp-gmail-api # Or run the MCP server (stdio) mcp-gmail ``` ### Running Tests ```bash pytest pytest --cov=mcp_gmail ``` ## Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Gmail MCP Server │ ├─────────────────────────────────────────────────────────────┤ │ MCP Interface (stdio) REST API (FastAPI) │ │ └── Tools for Claude └── Endpoints for HA │ ├─────────────────────────────────────────────────────────────┤ │ Gmail Client │ │ ├── Search & List ├── Categorization │ │ └── OAuth2 Auth └── Summary Generation │ ├─────────────────────────────────────────────────────────────┤ │ Gmail API │ │ └── google-api-python-client │ └─────────────────────────────────────────────────────────────┘ ``` ## Roadmap - [x] Read-only email access - [x] Category-based summaries - [x] Home Assistant REST API - [x] Docker deployment - [ ] Email sending (Phase 2) - [ ] Gmail labels modification - [ ] Scheduled summary notifications - [ ] IMAP fallback option ## License MIT License ## Troubleshooting ### OAuth Token Expired ```bash # Re-run authentication docker compose --profile setup run --rm gmail-mcp-auth ``` ### Container Won't Start Check that credentials exist: ```bash ls -la credentials/ # Should contain token.json ``` ### Home Assistant Can't Connect Ensure the container is on the same Docker network or use the host IP: ```yaml resource: http://192.168.1.100:8000/api/unread ```