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
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

# 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:

# 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

# 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

Email Data (for Home Assistant Sensors)

Summaries

Home Assistant Integration

Home Assistant Configuration

REST Sensors

Add to your configuration.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)

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

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:

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:

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):

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "exec", "-i", "gmail-mcp-server",
        "python", "-m", "mcp_gmail.server"
      ]
    }
  }
}

Available MCP Tools

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:

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)

# 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

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

• Read-only email access
• Category-based summaries
• Home Assistant REST API
• Docker deployment
• Email sending (Phase 2)
• Gmail labels modification
• Scheduled summary notifications
• IMAP fallback option

License

MIT License

Troubleshooting

OAuth Token Expired

# Re-run authentication
docker compose --profile setup run --rm gmail-mcp-auth

Container Won't Start

Check that credentials exist:

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:

resource: http://192.168.1.100:8000/api/unread