Gmail MCP Server
Provides read-only access to Gmail inbox with natural language search, email categorization, daily summaries organized by category (Navy, Kids, Financial, Action Items), and inbox statistics.
Uses 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 sensors to monitor unread email counts by category, trigger daily summary notifications via webhooks, and integrate Gmail data into Home Assistant automations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Gmail MCP Server show me unread emails from yesterday"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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!)
Related MCP server: Gmail MCP Server
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:8080to Authorized redirect URIsCopy 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-secret3. 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-authThis 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-mcpThe REST API will be available at http://localhost:8000
API Endpoints
Health & Status
Endpoint | Description |
| Health check with auth status |
| Inbox statistics |
Email Data (for Home Assistant Sensors)
Endpoint | Description |
| Total unread count |
| Unread count per category |
Summaries
Endpoint | Description |
| Full daily summary (JSON) |
| Daily summary as text |
| Category-specific summary |
Home Assistant Integration
Endpoint | Description |
| 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
- otherTemplate 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-circleAutomation: 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: POSTWebhook Integration
Configure in your .env:
HA_WEBHOOK_URL=http://homeassistant.local:8123/api/webhook/gmail_summary
HA_LONG_LIVED_TOKEN=your-long-lived-access-tokenThen 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 |
| Search emails with query and optional filters |
| Get full email content by ID |
| List unread emails with optional category filter |
| Generate categorized daily summary |
| Summary for a specific category |
| Current inbox statistics |
| List all Gmail labels |
| Create a new Gmail label |
| Delete a Gmail label |
| Show configured categories |
| Mark specific emails as read by IDs |
| Mark emails matching a query as read |
| Send an email (plain text or HTML) |
| Add labels to 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-gmailRunning Tests
pytest
pytest --cov=mcp_gmailArchitecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 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-authContainer Won't Start
Check that credentials exist:
ls -la credentials/
# Should contain token.jsonHome 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/unreadAvailable Tools
20 toolsgmail_add_label_to_messagesB
Add a label to one or more messages. Can specify messages by IDs or by search query.
Inputs: confirm (required), label_name, label_id, message_ids, +2 more.
gmail_category_summaryC
Get a summary of unread emails in one specific category. Returns email count and list of emails matching that category.
Inputs: category (required).
gmail_create_labelB
Create a new Gmail label with optional custom colors. Returns the new label's ID.
Inputs: label_name (required), background_color, text_color.
gmail_daily_summaryC
Generate a summary of recent emails organized by category. Shows unread counts and top emails in each category (Navy, Kids, Financial, Action Items).
Inputs: hours, include_read.
gmail_delete_labelA
Delete a Gmail label by name or ID. Cannot delete system labels. Requires confirmation.
Inputs: confirm (required), label_name, label_id.
gmail_get_categoriesA
List the configured email categories and their matching rules. Shows how emails are automatically categorized based on sender, subject, and labels.
Inputs: no named parameters.
gmail_get_emailA
Get the full content of a specific email by its Gmail message ID. Returns subject, sender, recipients, date, labels, and full body text.
Inputs: email_id (required).
gmail_get_packagesA
Get package delivery and shipping notification emails. Finds tracking info from Amazon, UPS, FedEx, USPS, and other carriers. Always includes read emails since you want to track all pending deliveries.
Inputs: days_back.
gmail_get_prioritiesA
Get priority emails based on the 'known_priorities' category in categories.yaml. Searches for emails matching configured senders (Navy, schools, family) and subjects (orders, deployments, scouts, financial alerts). Automatically excludes routine items like autopay confirmations.
Inputs: days_back, include_read.
gmail_inbox_statsB
Get current inbox statistics including total messages, unread count, starred count, and important message count.
Inputs: no named parameters.
gmail_list_labelsA
List all Gmail labels including both system labels (INBOX, SENT, etc.) and user-created labels. Returns label names and IDs.
Inputs: no named parameters.
gmail_list_unreadB
List unread emails from the inbox. Optionally filter by a pre-configured category such as navy, kids, financial, or action_required.
Inputs: category, max_results.
gmail_mark_as_read_by_idsA
Mark specific emails as read using their message IDs. Requires confirmation to execute.
Inputs: message_ids (required), confirm (required).
gmail_mark_as_read_by_queryA
Mark emails matching a search query as read. Use Gmail query syntax. Requires confirmation.
Inputs: query (required), confirm (required), max_emails.
gmail_mark_as_unread_by_idsA
Mark specific emails as unread using their message IDs. Requires confirmation to execute.
Inputs: message_ids (required), confirm (required).
gmail_mark_as_unread_by_queryA
Mark emails matching a search query as unread. Use Gmail query syntax. Requires confirmation.
Inputs: query (required), confirm (required), max_emails.
gmail_remove_label_from_messagesB
Remove a label from one or more messages. Can specify messages by IDs or by search query.
Inputs: confirm (required), label_name, label_id, message_ids, +2 more.
gmail_rename_labelA
Rename an existing Gmail label. Cannot rename system labels.
Inputs: new_name (required), label_name, label_id.
gmail_searchA
Search emails using Gmail query syntax. Returns a list of matching emails with subject, sender, date, and snippet. Use Gmail search operators like 'from:', 'to:', 'subject:', 'is:unread', 'has:attachment', 'after:', 'before:'.
Inputs: query (required), max_results.
gmail_send_emailB
Send an email. Can send new emails or reply to existing threads. Requires confirmation before sending.
Inputs: to (required), subject (required), body (required), confirm (required), +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 20 tools
Most tools have distinct purposes, such as gmail_get_email for retrieving full content and gmail_search for querying emails. However, some overlap exists between gmail_list_unread and gmail_category_summary, which both handle unread emails by category, potentially causing confusion. Overall, descriptions help clarify boundaries, but minor ambiguities remain.
All tool names follow a consistent snake_case pattern with a 'gmail_' prefix and descriptive verb_noun combinations, such as gmail_create_label and gmail_send_email. This predictability makes it easy for agents to understand and select tools without confusion or inconsistency in naming conventions.
With 20 tools, the count is borderline high for a Gmail-focused server, as it may feel heavy and could indicate over-specialization. While the tools cover various aspects like labels, summaries, and email management, a more streamlined set might improve usability without sacrificing functionality.
The tool set provides comprehensive coverage for Gmail operations, including CRUD for labels (create, delete, rename), email lifecycle management (send, read/unread, search), and specialized functions like summaries and package tracking. No significant gaps are apparent, ensuring agents can handle most email-related tasks effectively.
Maintenance
Related MCP Connectors
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Connect Gmail, iCloud Mail, Outlook, Yahoo Mail, Fastmail and other IMAP inboxes to ChatGPT, Claude and compatible AI assistants. Find emails by meaning across languages with semantic search. Ask AI to find customer conversations, summarize deadlines and draft follow-ups. Give a sales rep access to a shared outreach inbox or bring email into a compatible CRM. Share an iCloud custom-domain inbox with teammates without their own Apple ID or iCloud+ plan. Search results may be incomplete or stale; separate permissions control mail actions.
Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflowβ¦
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Gmail through the Gmail API to read, send, and manage emails. Supports multiple Gmail accounts with real-time monitoring and advanced features for email search and attachment handling.18Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables interaction with Gmail through the Gmail API with OAuth2 authentication. Supports reading, sending, searching emails, and managing read status through natural language.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to search, read, and download attachments from Gmail using natural language, with read-only access.2MIT
- FlicenseNot gradedqualityDmaintenanceAI-powered Gmail assistant that enables email management such as reading, searching, sending, summarizing, and organizing emails via natural language.-