# 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](https://console.cloud.google.com/)
2. Create a new project (or select existing)
3. Enable the [Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com)
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:

```bash
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):

```bash
uvx mcp-gmail-reader
```

---

## Backup & Recovery

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

| File | Where | Backup? | Recovery |
|------|-------|---------|----------|
| `~/.gmail-mcp/gcp-oauth.keys.json` | Local only | **YES — password manager** | Cannot regenerate without recreating GCP project |
| `~/.gmail-mcp/token.json` | Local only | No | Regenerated by running `uvx mcp-gmail-reader` once (browser flow) |
| `~/Documents/gmail-mcp/` (this repo) | Git | No need — `git clone` | `git clone https://github.com/Maheidem/gmail-mcp.git` |
| MCP registration | `~/.claude/settings.json` | No | Re-add the JSON snippet from "Claude Code (CLI)" section above |

### Recovery checklist (5 minutes after a fresh machine)

```bash
# 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`

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

### Claude Code (CLI)

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

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

### Cursor

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

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

### Windsurf

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

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

### VS Code + Continue

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

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

### Zed

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

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

### Custom credentials path

If your credentials are in a different location:

```json
{
  "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

```bash
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