Gmail Attachment Handler
Creates Gmail drafts with local file attachments, CC/BCC, HTML or plain-text bodies, and optional reply threading (returns a link to open the draft in Gmail), plus lists attachments in a thread and downloads attachments to a local folder. Sending email is blocked by design, so everything stays in Drafts for review.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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? |
| 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 |
| Lists every attachment in a thread (filename, size, and IDs). | No (read-only) |
| 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 APIThe 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
gogcall runs with--gmail-no-sendandGOG_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:
A Mac with Homebrew installed
Python 3.10 or newer (
python3 --version)A Google account, plus access to Google Cloud Console
Step 1: Install the gog CLI
brew install openclaw/tap/gogcliCheck that it installed:
which gog # usually /opt/homebrew/bin/gogStep 2: Create Google OAuth credentials
gog needs its own OAuth client to access your Gmail. In the Google Cloud Console:
Create a project, or pick an existing one.
Enable the Gmail API: go to APIs & Services → Library, search for "Gmail API", and click Enable.
Configure the OAuth consent screen:
User type: External
Under Test users, add your own Gmail address
Create credentials: go to APIs & Services → Credentials → Create credentials → OAuth client ID.
Application type: Desktop app
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 gmailStep 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.txtStep 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
envblock is optional. Without it, the server usesgog's default account and saves downloads to~/Downloads/Gmail. See Configuration.
Step 7: Restart Claude and verify
Quit the Claude desktop app completely (⌘Q, not just closing the window), then reopen it.
Open a new chat and check that the three tools appear in the tools menu.
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 |
| (none: | The Gmail account |
|
| Where downloaded attachments go. |
|
| Path to the |
|
| Seconds before a |
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 insideGOG_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. |
| Run the same command in Terminal (Step 4) to see the full error. Your login may have expired, so re-run |
| Set |
| 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-sendandGOG_GMAIL_NO_SENDfrom_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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
Bring Gmail, Outlook, iCloud Mail, Yahoo Mail, Fastmail and other IMAP mailboxes together. Search connected email, including semantic search; cached or indexed results may be incomplete or stale. Read messages and attachments, create drafts, send or reply when requested, and manage rules for new mail. Separate permissions control reading, attachments, drafts, sending and mailbox changes.
Your mailboxes in ChatGPT and Claude: Gmail, iCloud, Fastmail, any IMAP. Passwords stay yours.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.8MIT
- FlicenseNot gradedqualityDmaintenanceProvides Claude with Gmail capabilities including sending emails, managing drafts, and searching messages.-
- FlicenseNot gradedqualityDmaintenanceEnables reading unread emails and creating draft replies in Gmail via Claude Desktop.-
- AlicenseNot gradedqualityCmaintenanceConnects Claude Desktop to a local email client, enabling AI-powered email reading, searching, drafting, and organization while preventing sending or permanent deletion.1Apache 2.0