# Gmail MCP

## Gmail MCP

### What This Does

Enables Claude Code to search, read, send, and draft emails through your Gmail account.

### Source

* **Docker Hub:** <https://hub.docker.com/r/mcp/gmail>
* **Docker:** `mcp/gmail`
* **Alternative:** <https://github.com/GongRzhe/Gmail-MCP-Server>

### Prerequisites

* Docker Desktop installed
* @theentourageai.com Google account
* Google Cloud Project with Gmail API enabled

### Step 1: Create Local Config Folder

```bash
mkdir -p ~/.config/mcp/gmail
```

### Step 2: Get Credentials

#### Create Google Cloud OAuth Credentials

1. Go to <https://console.cloud.google.com>
2. Log in with your @theentourageai.com account
3. Create a new project or select existing one
4. Enable **Gmail API**:
   * Go to **APIs & Services → Library**
   * Search "Gmail API"
   * Click **Enable**

#### Create OAuth Client

1. Go to **APIs & Services → Credentials**
2. Click **Create Credentials → OAuth client ID**
3. Application type: **Desktop app**
4. Name: "Gmail MCP"
5. Click **Create**
6. Click **Download JSON**

#### Configure OAuth Consent Screen

1. Go to **APIs & Services → OAuth consent screen**
2. User type: **Internal** (for Workspace accounts)
3. Fill in:
   * App name: "Gmail MCP"
   * User support email: your @theentourageai.com email
   * Developer contact: your @theentourageai.com email
4. Add scopes:
   * `https://www.googleapis.com/auth/gmail.readonly`
   * `https://www.googleapis.com/auth/gmail.send`
   * `https://www.googleapis.com/auth/gmail.compose`
   * `https://www.googleapis.com/auth/gmail.modify`
5. Save

### Step 3: Save Credentials Locally

Move the downloaded OAuth JSON file:

```bash
mv ~/Downloads/client_secret_*.json ~/.config/mcp/gmail/credentials.json
```

### Step 4: Pull Docker Image

```bash
docker pull mcp/gmail
```

### Step 5: First Run (Authentication)

Run with interactive terminal to complete OAuth flow:

```bash
docker run -it --rm \
  -v ~/.config/mcp/gmail:/app/.credentials \
  -p 3000:3000 \
  mcp/gmail auth
```

1. A URL will appear in terminal
2. Open URL in browser
3. Log in with your @theentourageai.com account
4. Grant permissions
5. Token will be saved to `~/.config/mcp/gmail/token.json`

### Step 6: Add to Claude Code

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "${HOME}/.config/mcp/gmail:/app/.credentials",
        "mcp/gmail"
      ]
    }
  }
}
```

**Note:** If `${HOME}` doesn't expand, use absolute path:

```json
{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/yourname/.config/mcp/gmail:/app/.credentials",
        "mcp/gmail"
      ]
    }
  }
}
```

### Step 7: Verify It Works

Restart Claude Code and test:

```
Search my Gmail for emails from the last 7 days
```

Expected: List of recent emails from your inbox.

### Available Tools

| Tool                | Description                           |
| ------------------- | ------------------------------------- |
| `search_emails`     | Search emails with Gmail query syntax |
| `read_email`        | Read full email content by ID         |
| `send_email`        | Send a new email                      |
| `draft_email`       | Create a draft email                  |
| `modify_email`      | Add/remove labels, mark read/unread   |
| `delete_email`      | Move to trash                         |
| `list_email_labels` | List all labels                       |
| `create_label`      | Create new label                      |
| `create_filter`     | Create email filter                   |

### Troubleshooting

| Issue                     | Solution                                                      |
| ------------------------- | ------------------------------------------------------------- |
| "Access blocked"          | Add your email as test user in OAuth consent                  |
| Token expired             | Delete `token.json`, re-run auth                              |
| Permission denied         | Check OAuth scopes include required permissions               |
| "redirect\_uri\_mismatch" | Ensure OAuth client is Desktop type, not Web                  |
| Can't find credentials    | Check path is correct: `~/.config/mcp/gmail/credentials.json` |