Gmail MCP Server

An MCP (Model Context Protocol) server that provides Gmail integration for AI assistants like Claude. Search emails, read messages, and download attachments directly from your Gmail account.

Features

• Search emails using Gmail's powerful search syntax (from:, subject:, has:attachment, etc.)
• Read full email content including body and attachment metadata
• Download attachments to your local filesystem

Requirements

• Python 3.10+
• uv (recommended) or pip
• A Google Cloud project with Gmail API enabled

Installation

1. Clone and install dependencies

git clone https://github.com/yourusername/gmail-mcp.git
cd gmail-mcp
uv sync

2. Set up Google Cloud credentials

1. Go to Google Cloud Console
2. Create a new project (or select existing)
3. Enable the Gmail API
4. Go to APIs & Services > Credentials
5. Click Create Credentials > OAuth client ID
6. Select Desktop app as application type
7. Download the JSON file

3. Configure credentials

Save the downloaded credentials file:

mkdir -p ~/.gmail-mcp
mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/gcp-oauth.keys.json

Or set via environment variable:

export GMAIL_CREDENTIALS_PATH=/path/to/your/credentials.json

4. First-time authorization

Run the server once to complete OAuth:

uv run python -m gmail_mcp

A browser window will open for you to authorize access. The token is saved to ~/.gmail-mcp/token.json for future use.

Usage with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

macOS/Linux:

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/gmail-mcp", "python", "-m", "gmail_mcp"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": ["run", "--directory", "C:/path/to/gmail-mcp", "python", "-m", "gmail_mcp"]
    }
  }
}

Available Tools

search_emails

Search Gmail using Gmail search syntax.

search_emails(query="from:example@gmail.com", max_results=10)

Query examples:

• from:example@gmail.com - emails from specific sender
• subject:invoice - emails with subject containing "invoice"
• has:attachment - emails with attachments
• after:2024/01/01 - emails after date
• is:unread - unread emails
• label:important - emails with specific label

get_email

Get full email content by message ID.

get_email(message_id="abc123")

Returns: id, from, to, subject, date, body, attachments

download_attachment

Download email attachment to specified path.

download_attachment(
    message_id="abc123",
    attachment_id="xyz789",
    save_path="/path/to/save/file.pdf"
)

Development

# Run with MCP inspector
uv run mcp dev src/gmail_mcp/server.py

# Run tests
uv run pytest

# Lint
uv run ruff check src/

Security Notes

• Only gmail.readonly scope is used - this server cannot send or modify emails
• OAuth tokens are stored locally in ~/.gmail-mcp/token.json
• Never commit credentials or tokens to version control

License

MIT