Skip to main content
Glama
Gmail Attachment Handler

Gmail Attachment Handler

by julioterra
README.md
# Gmail Attachment Handler

An MCP server that lets the Claude desktop app work with Gmail attachments on your Mac. Claude can **create Gmail drafts with files attached** and **download attachments from emails you've received**.

It's designed to be safe by default. **It can't send email.** Everything it creates stays in your Drafts folder until you review and send it yourself.

---

## What it does

Claude's built-in Gmail connector can read and search your mail. It can't attach local files to a draft or save attachments to disk. This server fills those two gaps.

| Tool | What it does | Changes Gmail? |
|---|---|---|
| `create_gmail_draft` | Creates a draft with optional file attachments, CC/BCC, and HTML or plain-text body. It can also create the draft as a reply in an existing thread. Returns a link that opens the draft in Gmail. | Creates a draft only |
| `list_gmail_attachments` | Lists every attachment in a thread (filename, size, and IDs). | No (read-only) |
| `download_gmail_attachments` | Saves attachments to a folder on your Mac. It can save every attachment in a thread or one specific file. | No (read-only) |

### Example requests

Once it's set up, you can ask Claude things like:

- *"Draft an email to Ana with the PDF from my Downloads folder attached."*
- *"Reply to the accountant's thread with the two invoices attached, but leave it as a draft."*
- *"Download all the attachments from the latest email from the city about property tax into a folder called `FOLDER 2026`."*

### How it works

```
Claude desktop app  ──stdio──▶  server.py  ──subprocess──▶  gog CLI  ──HTTPS──▶  Gmail API
```

The server is a thin Python wrapper around [`gog`](https://github.com/openclaw/gogcli), a command-line Gmail client. `gog` handles authentication and talks to Google, and this server exposes a few of its commands to Claude as MCP tools.

### Safety

- **No send tool.** The server doesn't offer any tool that sends email.
- **Send is blocked at the CLI level too.** Every `gog` call runs with `--gmail-no-send` and `GOG_GMAIL_NO_SEND=1`, so a send command would be refused even if one were added by mistake.
- **Attachments are checked first.** Every attachment path has to exist on your Mac before a draft is created.

---

## Setup

Setup takes about 15–20 minutes and is only needed once.

### Before you start

You'll need:

- [ ] A Mac with [Homebrew](https://brew.sh) installed
- [ ] Python 3.10 or newer (`python3 --version`)
- [ ] The [Claude desktop app](https://claude.ai/download)
- [ ] A Google account, plus access to [Google Cloud Console](https://console.cloud.google.com)

### Step 1: Install the `gog` CLI

```bash
brew install openclaw/tap/gogcli
```

Check that it installed:

```bash
which gog        # usually /opt/homebrew/bin/gog
```

### Step 2: Create Google OAuth credentials

`gog` needs its own OAuth client to access your Gmail. In the [Google Cloud Console](https://console.cloud.google.com):

1. **Create a project**, or pick an existing one.
2. **Enable the Gmail API**: go to *APIs & Services → Library*, search for "Gmail API", and click **Enable**.
3. **Configure the OAuth consent screen**:
   - User type: **External**
   - Under *Test users*, **add your own Gmail address**
4. **Create credentials**: go to *APIs & Services → Credentials → Create credentials → OAuth client ID*.
   - Application type: **Desktop app**
5. **Download the JSON file**. It's named something like `client_secret_XXXX.json`.

### Step 3: Connect `gog` to your Gmail account

Give `gog` the credentials file, then sign in. A browser window opens for you to approve access.

```bash
gog auth credentials ~/Downloads/client_secret_*.json
gog auth add you@gmail.com --services gmail
```

### Step 4: Test `gog` on its own

Before you connect Claude, check that `gog` can create a draft. Replace the email address and file path with your own:

```bash
gog --gmail-no-send gmail drafts create \
  --to you@gmail.com \
  --subject "gog test" \
  --body "It works" \
  --attach ~/Downloads/any-file.pdf \
  --json
```

✅ **Success:** JSON output with a `draftId`, and a new draft with the attachment in your Gmail Drafts folder. You can delete the test draft.

### Step 5: Install the server

Clone this repository, then create a Python virtual environment and install the dependencies:

```bash
cd ~/Developer/gog-attach-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

### Step 6: Add the server to the Claude desktop app

Open **Claude → Settings → Developer → Edit Config**. This opens `~/Library/Application Support/Claude/claude_desktop_config.json`. Add an entry under `mcpServers`, using absolute paths:

```json
{
  "mcpServers": {
    "gmail-attachment-handler": {
      "command": "/Users/YOU/Developer/gog-attach-mcp/.venv/bin/python",
      "args": ["/Users/YOU/Developer/gog-attach-mcp/server.py"],
      "env": {
        "GOG_ACCOUNT": "you@gmail.com",
        "GOG_BIN": "/opt/homebrew/bin/gog",
        "GOG_DOWNLOAD_DIR": "/Users/YOU/Downloads/Gmail"
      }
    }
  }
}
```

> 💡 The whole `env` block is optional. Without it, the server uses `gog`'s default account and saves downloads to `~/Downloads/Gmail`. See [Configuration](#configuration).

### Step 7: Restart Claude and verify

1. **Quit the Claude desktop app completely** (⌘Q, not just closing the window), then reopen it.
2. Open a new chat and check that the three tools appear in the tools menu.
3. Try it: *"Create a Gmail draft to me with subject 'MCP test' and attach ~/Downloads/any-file.pdf."*

✅ **Success:** Claude returns a Gmail link that opens the draft with the file attached.

---

## Configuration

All settings are optional environment variables, set in the `env` block of the Claude config.

| Variable | Default | Purpose |
|---|---|---|
| `GOG_ACCOUNT` | *(none: `gog`'s default account)* | The Gmail account `gog` acts on. Recommended if you've added more than one account to `gog`. |
| `GOG_DOWNLOAD_DIR` | `~/Downloads/Gmail` | Where downloaded attachments go. |
| `GOG_BIN` | `gog` on your `PATH`, otherwise `/opt/homebrew/bin/gog` | Path to the `gog` executable. |
| `GOG_TIMEOUT` | `120` | Seconds before a `gog` command times out. |

**Download folders:** when you call `download_gmail_attachments`, `out_dir` controls where files are saved.
- A **bare name** (e.g. `"FOLDER 2026"`) creates a subfolder inside `GOG_DOWNLOAD_DIR`.
- An **absolute path** is used exactly as given.

---

## Troubleshooting

| Problem | Fix |
|---|---|
| Tools don't show up in Claude | Fully quit (⌘Q) and reopen Claude. It only loads local servers at launch. Check that the paths in your config are absolute and correct. |
| `gog failed (exit …)` errors | Run the same command in Terminal (Step 4) to see the full error. Your login may have expired, so re-run `gog auth add …`. |
| `gog` not found | Set `GOG_BIN` to the output of `which gog`. |
| `Attachment not found` | Attachment paths have to be absolute paths to files that exist on your Mac. |
| Google says "app not verified" during sign-in | That's expected for a personal OAuth client. Click *Advanced → Continue*. Make sure you added yourself as a test user (Step 2). |

---

## Development notes

- **After editing `server.py`**, fully quit and reopen the Claude desktop app to load your changes.
- **To enable sending later**, add a tool that calls `gog gmail drafts send <id>`. Then remove `--gmail-no-send` and `GOG_GMAIL_NO_SEND` from `_run_gog()`. Think it through first, because this removes the main safety guarantee.

---

## License

MIT. See [LICENSE](LICENSE).