OneShotForge Buy — $49 →

May 19, 2026 · 8 min read

How to give Claude Code inbox access

Tutorial for plugging Claude Code into your IMAP/SMTP inbox via MCP. Setup, the 15-tool surface, what works, common gotchas.

Claude Code is great at the things you'd expect a senior engineer to be great at: refactoring, writing tests, walking through a codebase, debugging. Less obvious: it's also pretty good at running an inbox, if you give it the right tools.

I started doing this seriously a few months ago, after I got tired of the morning triage that took fifteen minutes every day. I wanted to say claude "summarize anything that's not a recruiter and draft a polite decline for the recruiters" and walk away.

To get there, you need three things:

  1. A Claude Code installation (you probably have one)
  2. An MCP server that knows how to talk to your inbox over IMAP and SMTP
  3. A working .mcp.json so Claude Code knows where to find it

The first one's already done. The third one's a one-liner. The second is the actual question.

A 60-second refresher on MCP

If you've been using Claude Code for a while, MCP (Model Context Protocol) is the thing that lets the agent reach beyond its context window into your tools. Anthropic ships it as an open spec, and the way you plug a tool in is a single entry in ~/.claude.json or .mcp.json pointing at a server binary.

A server can be anything: a Python script you wrote yourself, an npm package someone shipped, a Docker container running on your laptop. As long as it speaks the MCP protocol over stdio or HTTP, Claude Code will talk to it.

For email specifically, you have two real paths.

Path 1: write the MCP server yourself

If you're comfortable with imapflow or node-imap on the Node side, or imaplib in Python, you can build a server in an afternoon. The minimum viable version is list_messages, get_message, and send_message over a single account.

I did this first. It worked. Then I needed search across folders, then attachments, then drafts that Claude could revise before send, then multi-account support, then proper error handling for the dozen ways IMAP can return things that aren't what you expected.

A weekend project turned into the better part of a month. Which is how I ended up with what became mcp-email.

Path 2: use an existing MCP server

If "month of evenings" is not on your roadmap, you have a few off-the-shelf options. Most of them do the obvious two operations (read, send) and stop there. If you only need notification-style "tell me when something new arrives" or "send this drafted message," any of them work.

The moment you want Claude to actually triage — search across folders, fetch attachments, draft and revise, move messages around, flag for follow-up — you need a server with the boring operations covered. That's the niche mcp-email fills.

I'm the maker, so take this with the usual grain of salt. The full feature list is on oneshotforge.com/mcp-email. The rest of this article describes what the setup looks like in practice, whether you end up using mcp-email or building your own.

The setup, step by step

Step 1: pick a provider and get the right credentials

You want IMAP + SMTP credentials, ideally an app password rather than your main account password. Common providers and what to ask for:

If you're using your inbox for business, set up SPF, DKIM, and DMARC records on the sending domain before you ask Claude to send anything. mail-tester.com will give you a 0-10 score on the resulting setup; aim for 10/10. My setup on hello@oneshotforge.com scores 10/10 and I'm pretty confident a 10/10 mail-tester score correlates with not landing in spam.

Step 2: configure the MCP server

For mcp-email specifically, the config lives in a .env file:

ACCOUNT_MAIN_EMAIL=hello@oneshotforge.com
ACCOUNT_MAIN_PASSWORD=...
ACCOUNT_MAIN_IMAP_HOST=imap.hostinger.com
ACCOUNT_MAIN_IMAP_PORT=993
ACCOUNT_MAIN_SMTP_HOST=smtp.hostinger.com
ACCOUNT_MAIN_SMTP_PORT=465

Multi-account just means more blocks: ACCOUNT_GMAIL_*, ACCOUNT_PROTON_*, and so on. Every tool call from Claude will include an account argument, so the agent never confuses which inbox is being read or sent from.

Other servers will have slightly different conventions, but the credentials are the same.

Step 3: wire it into Claude Code

In your project (or globally in ~/.claude.json), add:

{
  "mcpServers": {
    "mcp-email": {
      "command": "node",
      "args": ["/path/to/mcp-email/dist/index.js"],
      "env": { "DOTENV_PATH": "/path/to/mcp-email/.env" }
    }
  }
}

Restart Claude Code. Ask it list my unread messages. If a list of subject lines comes back, you're done.

The 15 tools, briefly

The tools fall into three buckets.

Reading: list_folders, list_messages, search_messages, get_message, get_thread, get_attachment. This is the part where Claude needs to figure out what's in the inbox. The thread tool is the one I rely on most because Claude reasons better when it can see the chain of replies, not just the latest message.

Writing: send_message, create_draft, reply_message. The create_draft tool is essential. I never let the agent send anything without me reading the draft in Gmail first, and create_draft is what makes that workflow possible.

Management: move_message, copy_message, delete_message, mark_message (read/unread/flag), and folder ops (create_folder, rename_folder, delete_folder). The boring stuff. The reason you need this is so Claude can actually file things — "move this to triage/recruiters" — instead of just listing them and forgetting.

What Claude is good at, what it isn't

After a few months of running this daily, here's the actual capability shape.

Good at:

Bad at:

Common gotchas

A few things that bit me early:

Closing

The honest pitch: if you spend more than 15 minutes a day on triage, this pays for itself in a week, even at the highest possible interpretation of your hourly rate. If you're at "I check email three times a day, it's fine," you don't need it.

mcp-email is distributed as a paid product. After checkout on https://shop.oneshotforge.com/l/mcp-email you get the full TypeScript source code, the Docker compose setup, the per-provider config docs, and a perpetual commercial license. The whole thing fits in a single zip. The README walks you through your first .mcp.json entry in Claude Code.

If you build something interesting on top, hit me at hello@oneshotforge.com. I read everything.