Skip to main content
Glama
Gmail Attachment Handler

Gmail Attachment Handler

by julioterra

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, 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.


Related MCP server: Gmail MCP Local Server

Setup

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

Before you start

You'll need:

Step 1: Install the gog CLI

brew install openclaw/tap/gogcli

Check that it installed:

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:

  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.

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:

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:

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:

{
  "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.

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI-powered inbox management with natural language commands through Claude Desktop. Supports sending, reading, searching, organizing emails, and managing labels using Gmail API with automatic authentication.
      8
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects Claude Desktop to a local email client, enabling AI-powered email reading, searching, drafting, and organization while preventing sending or permanent deletion.
      1
      Apache 2.0