Which integrations are available for this server?

Provides read-only access to [Gmail](/mcp/servers/integrations/gmail) inbox with natural language search, email categorization, daily summaries organized by category (Navy, Kids, Financial, Action Items), and inbox statistics. Uses [Google Cloud](/mcp/servers/integrations/google-cloud) Console for OAuth credential management and Gmail API access configuration to authenticate and interact with Gmail services. Exposes REST API endpoints for [Home Assistant](/mcp/servers/integrations/home-assistant) sensors to monitor unread email counts by category, trigger daily summary notifications via webhooks, and integrate Gmail data into Home Assistant automations.

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

Go to Google Cloud Console
Create a new project or select existing
Enable the Gmail API:
- Navigate to "APIs & Services" → "Enable APIs"
- Search for "Gmail API" and enable it
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:

Open a browser window for Google authentication
Request permission to read your Gmail
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

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:

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, Home Assistant, or other MCP clients via SSE transport.

Claude Desktop Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{ "mcpServers": { "gmail": { "command": "npx", "args": ["-y", "mcp-remote", "http://YOUR_SERVER_IP:8001/mcp/sse", "--allow-http"] } } }

Home Assistant MCP Integration

The server exposes SSE endpoints for MCP connections:

/mcp/sse - Primary MCP SSE endpoint
/sse - Alias endpoint for Home Assistant compatibility

Available MCP Tools

Tool	Description
`gmail_search`	Search emails with query and optional filters
`gmail_get_email`	Get full email content by ID
`gmail_list_unread`	List unread emails with optional category filter
`gmail_daily_summary`	Generate categorized daily summary
`gmail_category_summary`	Summary for a specific category
`gmail_inbox_stats`	Current inbox statistics
`gmail_list_labels`	List all Gmail labels
`gmail_create_label`	Create a new Gmail label
`gmail_delete_label`	Delete a Gmail label
`gmail_get_categories`	Show configured categories
`gmail_mark_as_read_by_ids`	Mark specific emails as read by IDs
`gmail_mark_as_read_by_query`	Mark emails matching a query as read
`gmail_send_email`	Send an email (plain text or HTML)
`gmail_add_labels_to_messages`	Add labels to messages
`gmail_remove_labels_from_messages`	Remove labels from messages

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
Gmail labels management (create, delete, add to messages, remove from messages)
Mark emails as read
SSE transport with session isolation
Gemini-compatible tool schemas
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

Gmail MCP Server

Gmail MCP Server

Features

Quick Start

1. Google Cloud Setup

2. Configuration

3. Initial Authentication (OAuth)

4. Start the Server

API Endpoints

Health & Status

Email Data (for Home Assistant Sensors)

Summaries

Home Assistant Integration

Home Assistant Configuration

REST Sensors

Template Sensors (from attributes)

Automation: Daily Summary Notification

Webhook Integration

MCP Server Usage

Claude Desktop Configuration

Home Assistant MCP Integration

Available MCP Tools

Example Queries

Customizing Categories

Matcher Types

Development

Local Setup (without Docker)

Running Tests

Architecture

Roadmap

License

Troubleshooting

OAuth Token Expired

Container Won't Start

Home Assistant Can't Connect

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API