Gmail MCP Server

Production-ready Model Context Protocol (MCP) server for Gmail. Exposes search, read, send, draft, attachment, label, and delete operations to AI agents via FastMCP and the Google Gmail REST API.

Architecture

AI Agent (Claude, Cursor, VS Code)
        │
        ▼
   MCP Protocol (stdio)
        │
        ▼
   FastMCP Server (app.py)
        │
   ┌────┴────┬──────────┐
   ▼         ▼          ▼
 Tools   Resources   Prompts
   │         │          │
   └────┬────┴──────────┘
        ▼
   GmailClient (gmail_client.py)
        │
        ▼
   Authentication (auth.py)
        │
        ▼
   Google Gmail REST API

Design principles:

• MCP tools never call Google APIs directly — all requests go through GmailClient
• Authentication lives exclusively in auth.py
• Configuration lives exclusively in config.py
• Business logic is separated from the MCP layer

Features

Tools

Tool	Description
search_email	Search by sender, recipient, subject, label, date, attachments, unread, or custom query
read_email	Read full email with subject, body, attachments, labels, thread ID
send_email	Send plain text or HTML with CC, BCC, attachments
create_draft	Create drafts with HTML and attachments
download_attachment	Download a single attachment
download_all_attachments	Download all attachments from a message
save_attachment	Save attachment to local disk
list_labels	List all Gmail labels
create_label	Create a new label
delete_label	Delete a user label
modify_label	Update label properties
delete_email	Permanently delete a message
trash_email	Move message to trash
restore_email	Restore message from trash

Resources (read-only)

URI	Description
gmail://inbox	Recent inbox messages
gmail://unread	Unread messages
gmail://labels	All labels
gmail://drafts	Draft messages
gmail://recent	Messages from the last 7 days

Prompts

Prompt	Description
summarize_unread_emails	Search unread → read → summarize workflow
find_invoice_emails	Find invoices → download PDFs → return metadata

Installation

Prerequisites

• Python 3.11+
• A Google Cloud project with Gmail API enabled
• OAuth 2.0 Desktop client credentials

Setup

# Clone or navigate to the project
cd gmail_mcp_server

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env

Place your OAuth client secrets file at credentials.json in the project root (or set GMAIL_CREDENTIALS_PATH in .env).

Docker (recommended)

Run the server in a container — no local Python virtualenv required.

Prerequisites

• Docker and Docker Compose
• credentials.json in the project root
• touch token.json before first run (empty file so Docker can mount it)

First-time OAuth (inside Docker)

docker compose --profile auth run --rm --service-ports gmail-auth

Opens a browser on your machine. After sign-in, token.json is saved on the host.

Run the MCP server

docker compose run --rm -i gmail-mcp

Connect Cursor via Docker

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/Users/varunnegi/gmail_mcp_server/docker-compose.yml",
        "run",
        "--rm",
        "-i",
        "gmail-mcp"
      ]
    }
  }
}

Use the absolute path to your docker-compose.yml.

Docker vs local venv

Approach	Pros	Cons
Docker	Reproducible, no local Python setup, easy cleanup	Slightly slower startup, OAuth needs one extra step
Local venv	Faster startup, simpler OAuth in browser	Must manage Python version and dependencies

You can delete .venv if you use Docker exclusively.

Local Installation (without Docker)

Prerequisites

• Python 3.11+
• A Google Cloud project with Gmail API enabled
• OAuth 2.0 Desktop client credentials

Setup

# Clone or navigate to the project
cd gmail_mcp_server

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env

Place your OAuth client secrets file at credentials.json in the project root.

1. Go to Google Cloud Console
2. Create a new project (or select an existing one)
3. Enable the Gmail API: APIs & Services → Library → search "Gmail API" → Enable
4. Configure OAuth consent screen: APIs & Services → OAuth consent screen
   • Choose External (or Internal for Workspace)
   • Add scopes: gmail.readonly, gmail.send, gmail.modify, gmail.labels, gmail.compose
   • Add your email as a test user (while in testing mode)
5. Create credentials: APIs & Services → Credentials → Create Credentials → OAuth client ID
   • Application type: Desktop app
   • Download the JSON file and save as credentials.json

OAuth Setup

On first run, the server opens a browser window for Google OAuth consent. After approval, a token.json file is created and reused on subsequent runs. Tokens refresh automatically.

python app.py

To force re-authentication, delete token.json and restart.

Running the Server

source .venv/bin/activate
python app.py

The server uses stdio transport — it communicates over stdin/stdout with the MCP host.

Connecting Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/gmail_mcp_server/.venv/bin/python",
      "args": ["/path/to/gmail_mcp_server/app.py"]
    }
  }
}

Restart Claude Desktop after saving.

Connecting Cursor

Add to Cursor MCP settings (.cursor/mcp.json or Settings → MCP):

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/gmail_mcp_server/.venv/bin/python",
      "args": ["/path/to/gmail_mcp_server/app.py"]
    }
  }
}

Connecting VS Code

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "gmail": {
      "type": "stdio",
      "command": "/path/to/gmail_mcp_server/.venv/bin/python",
      "args": ["/path/to/gmail_mcp_server/app.py"]
    }
  }
}

Example MCP Tool Calls

Search unread emails from a sender:

{
  "tool": "search_email",
  "arguments": {
    "sender": "billing@example.com",
    "unread": true,
    "max_results": 10
  }
}

Read a specific email:

{
  "tool": "read_email",
  "arguments": {
    "message_id": "18abc123def456"
  }
}

Send an email:

{
  "tool": "send_email",
  "arguments": {
    "to": "recipient@example.com",
    "subject": "Hello from MCP",
    "body": "This email was sent via the Gmail MCP Server."
  }
}

Troubleshooting

Issue	Solution
credentials.json not found	Download OAuth client JSON from Google Cloud Console
Browser auth fails	Ensure redirect URI http://localhost is allowed for Desktop OAuth
TokenExpiredError	Delete token.json and re-authenticate
403 Insufficient Permission	Re-auth with updated scopes; delete old token.json
Server not appearing in host	Verify absolute paths in MCP config; check python app.py runs without errors
Empty search results	Confirm Gmail query syntax; try custom_query: "in:inbox"

Enable debug logging:

LOG_LEVEL=DEBUG python app.py

Security

• OAuth tokens and email bodies are never logged
• Attachment contents are never logged
• Gmail queries are sanitized before API calls
• Never commit credentials.json, token.json, or .env

Project Structure

gmail_mcp_server/
├── app.py              # FastMCP entry point
├── config.py           # Configuration and constants
├── auth.py             # OAuth2 authentication
├── gmail_client.py     # Gmail API business layer
├── requirements.txt
├── .env.example
├── tools/              # MCP tool modules
├── resources/          # MCP read-only resources
├── prompts/            # MCP prompt templates
└── utils/              # Parser, formatter, logger, exceptions

Future Roadmap

• [ ] Google Drive MCP integration
• [ ] Microsoft Outlook MCP integration
• [ ] Slack MCP integration
• [ ] Notion MCP integration
• [ ] SharePoint MCP integration
• [ ] Batch email operations
• [ ] Pub/Sub push notification support
• [ ] Multi-account support
• [ ] HTTP transport for remote deployment

License

Apache 2.0