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

Related MCP server: Gmail Streamable MCP Server

Features

Tools

Resources (read-only)

Prompts

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

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

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