Gmail MCP Server

Gmail MCP Server

An MCP (Model Context Protocol) server for reading and sending Gmail via IMAP/SMTP. Exposes Gmail operations as MCP tools usable by Claude and other AI models, and includes a web UI for managing your inbox directly in the browser.

Features

• List Emails: Retrieve emails from any Gmail folder
• Get Unread Emails: Fetch only unread messages
• Search Emails: Search with IMAP search criteria (by sender, date, subject, etc.)
• Get Emails from Sender: Retrieve all emails from a specific sender
• Get Emails by Subject: Search by subject text
• Send Emails: Compose and send emails via SMTP
• List Folders: View all available Gmail folders
• Get Email Details: Fetch complete details of a specific email

Prerequisites

• Docker installed on your system
• A Gmail account with IMAP enabled and an App Password generated

Quick Start

1. Enable Gmail IMAP and generate an App Password

1. Enable 2-Factor Authentication: https://myaccount.google.com/security
2. Generate an App Password for Mail: https://myaccount.google.com/apppasswords
3. Note your Gmail address and the generated app password — you'll need them below

2. Clone and configure

git clone https://github.com/chinmay4382/gmail-mcp-server.git
cd gmail-mcp-server
cp .env.example .env

Edit .env with your credentials:

EMAIL_ADDRESS=your_email@gmail.com
EMAIL_PASSWORD=your_app_password
IMAP_SERVER=imap.gmail.com
SMTP_SERVER=smtp.gmail.com
ANTHROPIC_API_KEY=your_anthropic_api_key

3. Run with Docker

Option A — Web UI (browser app):

docker compose up email-ui

Then open http://localhost:8000 in your browser.

Option B — MCP server (for Claude Desktop / MCP clients):

docker compose up email-mcp-server

Available MCP Tools

list_emails

List emails from a folder.

Parameters:

• max_results (int, default: 10): Number of emails to retrieve
• unread_only (bool, default: false): Only return unread emails
• folder (string, default: "INBOX"): Gmail folder name

get_unread_emails

Get unread emails from a folder.

Parameters:

• max_results (int, default: 10): Number of unread emails to retrieve
• folder (string, default: "INBOX"): Gmail folder name

get_emails_from_sender

Get emails from a specific sender.

Parameters:

• sender (string): Email address of the sender
• max_results (int, default: 10): Number of emails to retrieve
• folder (string, default: "INBOX"): Gmail folder name

search_emails

Search emails using IMAP search criteria.

Parameters:

• query (string): IMAP search query
• max_results (int, default: 10): Maximum results to return
• folder (string, default: "INBOX"): Gmail folder to search

Query examples:

• UNSEEN — Unread messages
• FROM "user@example.com" — Emails from a specific sender
• SUBJECT "invoice" — Emails with "invoice" in subject
• FLAGGED — Starred emails
• SINCE "1-Jan-2024" — Emails since a date
• UNSEEN FROM "user@example.com" — Combine criteria

get_emails_by_subject

Get emails by subject text.

Parameters:

• subject (string): Subject text to search for
• max_results (int, default: 10): Maximum emails to retrieve
• folder (string, default: "INBOX"): Gmail folder to search

send_email

Send an email.

Parameters:

• recipient (string): Recipient email address
• subject (string): Email subject
• body (string): Email body text
• html (bool, default: false): If true, body is treated as HTML

get_email_details

Get full details of a specific email.

Parameters:

• message_id (string): Email ID from IMAP

list_folders

List all available Gmail folders.

Configuration

Troubleshooting

"Authentication failed"

• Make sure you're using a Gmail App Password, not your regular Gmail password
• Confirm IMAP is enabled in Gmail Settings → See all settings → Forwarding and POP/IMAP

"Connection refused"

• Verify IMAP is enabled in your Gmail account settings
• Check that your firewall doesn't block port 993 (IMAP) or 587 (SMTP)

"No module named 'mcp'"

• Rebuild the Docker image: docker compose build

File Structure

gmail-mcp-server/
├── gmail_mcp_server.py   # MCP server entry point
├── gmail_client.py       # IMAP/SMTP client wrapper
├── api_server.py         # FastAPI REST server for the web UI
├── ui/
│   ├── index.html        # Web UI markup
│   ├── app.js            # Web UI JavaScript
│   └── styles.css        # Web UI styles
├── Dockerfile            # Docker build configuratio