Gmail MCP Server

An MCP (Model Context Protocol) server that provides Gmail integration for AI assistants. 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

Quick Start

1. 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 and save it:

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

2. First-time authorization

Run once to complete OAuth (opens browser):

uvx mcp-gmail-reader

Backup & Recovery

After a fresh OS install or losing your machine, here's what to restore:

Recovery checklist (5 minutes after a fresh machine)

# 1. Clone the source
git clone https://github.com/Maheidem/gmail-mcp.git ~/Documents/gmail-mcp

# 2. Restore credentials from your password manager
mkdir -p ~/.gmail-mcp
# (paste gcp-oauth.keys.json into ~/.gmail-mcp/)

# 3. Install + first-run authorization (opens browser)
uvx mcp-gmail-reader

# 4. Re-register in Claude Code (see "Claude Code (CLI)" section below)

The OAuth credentials JSON is the only thing that cannot be recovered without doing the full Google Cloud Console setup again. Back it up.

Setup by AI Tool

Claude Desktop

Add to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["mcp-gmail-reader"]
    }
  }
}

Claude Code (CLI)

Add to your MCP settings (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["mcp-gmail-reader"]
    }
  }
}

Cursor

Add to Cursor's MCP config (Settings > MCP Servers):

{
  "gmail": {
    "command": "uvx",
    "args": ["mcp-gmail-reader"]
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["mcp-gmail-reader"]
    }
  }
}

VS Code + Continue

Add to Continue's config (~/.continue/config.json):

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": ["mcp-gmail-reader"]
        }
      }
    ]
  }
}

Zed

Add to Zed's settings (~/.config/zed/settings.json):

{
  "context_servers": {
    "gmail": {
      "command": {
        "path": "uvx",
        "args": ["mcp-gmail-reader"]
      }
    }
  }
}

Custom credentials path

If your credentials are in a different location:

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["mcp-gmail-reader"],
      "env": {
        "GMAIL_CREDENTIALS_PATH": "/path/to/your/credentials.json"
      }
    }
  }
}

Available Tools

search_emails

Search Gmail using Gmail search syntax.

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

• in:inbox - emails in inbox

get_email

Get full email content by message ID (returned from search_emails).

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

download_attachment

Download email attachment to specified path.

Parameters: message_id, attachment_id, save_path

Development

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

# Run server
uv run python -m gmail_mcp

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

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