Skip to main content
Glama
murphy360

Gmail MCP Server

by murphy360
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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

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

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:

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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/murphy360/mcp_gmail'

If you have feedback or need assistance with the MCP directory API, please join our Discord server