gmail-imap
A Gmail (and any IMAP/SMTP) plugin for Claude Code and Claude Cowork — with first-class attachment download.
The attachment story is the headline. Most email integrations for AI agents stop at metadata: they tell the model "this message has 3 attachments" and that's it. This one writes the actual files to disk and hands the agent absolute paths it can pipe into every other tool — Read, PDF/XLSX/DOCX skills, OCR, your own scripts. Invoices, contracts, photos, CSVs — they land somewhere the agent can act on them.
Plus the rest of the boring-but-essential mailbox surface: read, search, send, reply with proper threading, star, move. Built on imapflow + mailparser + nodemailer — battle-tested IMAP/SMTP libs, no SaaS dependencies, no OAuth dance.
You: "Open the latest email from my accountant and download the PDFs."
Claude → gmail_messages_search { from: "[email protected]", limit: 1 }
Claude → gmail_message_attachments_save { uid: 4128 }
↳ saved 2 files to ~/.gmail-imap/attachments/INBOX-4128/
- Invoice_2026_05.pdf (124 KB)
- Receipts_April.pdf (812 KB)
Claude → Read("~/.gmail-imap/attachments/INBOX-4128/Invoice_2026_05.pdf")
↳ "Total due: €2,340. Payment by 2026-05-31. Reference: INV-2845."
Heritage: this plugin started life as openclaw-gmail-plugin (this same repo, renamed). v1.0.0 is a full port to the Model Context Protocol and the Claude plugin format. The IMAP/SMTP engine is unchanged.
What's in the plugin
| Component | Purpose |
|---|
MCP server (gmail-imap) | 9 gmail_* tools over stdio. Bundled as a single self-contained JS file — Node.js is the only runtime requirement. |
Skill (email-workflows) | Teaches Claude the search operator syntax, attachment chaining, localized mailbox gotchas, and the send-confirmation protocol. Loads only when relevant. |
Tools
| Tool | Purpose |
|---|
gmail_mailboxes_list | List folders/labels on the account. |
gmail_messages_search | Server-side IMAP search. Free text (AND), OR alternation, inline Gmail operators (from:, has:attachment, is:unread, after:…), or raw Gmail syntax via gmailRaw. Defaults to the last 30 days when no date filter is given. |
gmail_message_get | Fetch one message by UID with full body. HTML→text fallback for HTML-only mail. |
gmail_thread_get | Fetch a whole Gmail conversation chronologically (X-GM-EXT-1). |
gmail_message_attachments_save | Download all (or selected) attachments to disk; returns absolute paths. |
gmail_message_update | Mark read/unread, star/unstar. |
gmail_message_move | Move between mailboxes (e.g. INBOX → Archive). |
gmail_message_send | Send a new email. Requires confirm: true by default. |
gmail_message_reply | Reply (or reply-all) with proper In-Reply-To/References threading and quoting. Requires confirm: true by default. |
Quick start
1. Get a Gmail App Password
Requires 2-Step Verification on your Google account. Then:
- Go to https://myaccount.google.com/apppasswords
- Create an app password (any name)
- Copy the 16-character password (spaces shown in the UI are cosmetic — they are stripped automatically)
2. Configure credentials
Create ~/.gmail-imap/config.json:
{
"username": "[email protected]",
"appPassword": "xxxxxxxxxxxxxxxx",
"fromName": "Your Name"
}
Or use environment variables instead (they override the file): GMAIL_USERNAME, GMAIL_APP_PASSWORD, and optionally GMAIL_FROM, GMAIL_FROM_NAME, GMAIL_REPLY_TO, GMAIL_IMAP_HOST/GMAIL_IMAP_PORT/GMAIL_IMAP_SECURE, GMAIL_SMTP_HOST/GMAIL_SMTP_PORT/GMAIL_SMTP_SECURE, GMAIL_DEFAULT_MAILBOX, GMAIL_DEFAULT_SEARCH_LIMIT, GMAIL_ATTACHMENTS_DIR, GMAIL_REQUIRE_SEND_CONFIRMATION. GMAIL_IMAP_CONFIG overrides the config file path itself.
3. Install the plugin
Claude Cowork: drop the gmail-imap.plugin file into a chat and accept it.
Claude Code (from a local clone):
git clone https://github.com/manuelfedele/gmail-imap.git
cd gmail-imap
npm install && npm run build
claude plugin install ./
The prebuilt server is committed at dist/index.cjs, so installing straight from the repo also works without building.
4. Try it
"List my Gmail folders, then show me the 5 most recent unread messages."
Configuration reference
All fields go in ~/.gmail-imap/config.json (or the matching env var).
