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).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues