Repository avatar
AI Tools
v1.0.0
active

imap-mcp

io.github.harrywang/imap-mcp

Remote MCP server for any IMAP mailbox: OAuth, multiple mailboxes, attachments, approved sends

Documentation

IMAP MCP

A personal MCP server that gives AI agents (Claude, ChatGPT, Cursor, VS Code, or any MCP client) access to any IMAP mailbox.

IMAP MCP sign-in page

  • Next.js 16 + Better Auth + shadcn/ui, deployed on Vercel with a Neon Postgres database. One Vercel account covers everything.
  • OAuth login, nothing secret in the URL. Your agent registers itself (dynamic client registration). You sign in once and approve it on a consent page. Access tokens last 1 hour, refresh tokens 30 days.
  • Multiple mailboxes, kept apart. Add up to 20 (MAIL_2, MAIL_3, …). Every result says which mailbox it came from, replies go out from the mailbox the original arrived in, and when it's unclear which one you mean, the agent is told to ask instead of guessing.
  • Reads attachments. PDFs, Word, Excel/CSV, text, calendar invites and images, returned as standard MCP content any client can use. If something can't be read, such as a scanned PDF, the agent is told to say so instead of guessing.
  • Nothing is sent without your yes. The agent saves every message as a draft, shows it to you, and can send that exact draft only after you approve it in the chat. Set ALLOW_SEND=false for drafts only.
  • Mail passwords never touch the database. They live only in Vercel environment variables. The database holds login and OAuth data.

Deploy

Deploy with Vercel

1. Create the project

Click Deploy. Pick your Vercel team, name the new private repository (Vercel copies this repo into your GitHub account), and click Create.

Vercel New Project: repository name and team

2. Add the Neon database

Click Add next to Neon, then:

  1. Accept the terms.
  2. Choose the Free plan and leave Auth and Realtime off. This app has its own login and doesn't use them.
  3. Click Create, then Done when the database is ready.

The Free plan (1 GB, 100 compute hours a month) is plenty for this app. It's only offered if your Vercel team doesn't have Neon yet; a team that already uses Neon on a paid plan puts new databases on that plan. A personal Hobby team is the easy way to stay free.

Add Products: Neon Neon terms of service Neon plan: Free, Auth and Realtime off Neon confirmation Neon database ready

3. Fill in 4 values and deploy

NameValue
MAIL_1Your mailbox address
MAIL_1_PASSWORDIts password, or an app password
ADMIN_PASSWORDYour login for this app, 12+ characters. Run openssl rand -base64 24 and save it in your password manager.
BETTER_AUTH_SECRETRun openssl rand -base64 32. You never type this one.
Vercel: database added, environment variables, Deploy

Click Deploy.

4. Sign in

Open your deployment (https://<your-app>.vercel.app), sign in with your ADMIN_PASSWORD, and check that the mailbox test shows ✅.

The username, admin@imap-mcp.local, is filled in for you and doesn't matter. This app has exactly one login and sign-up is disabled, so the password is the only thing that protects it. The username has to look like an email address because Better Auth's email-and-password sign-in requires one, but no mail is ever sent to it. To change it, set ADMIN_EMAIL.

5. Connect Claude

  1. In claude.ai or Claude Desktop, open Settings → Connectors → Add custom connector. Enter a name and your connector URL, https://<your-app>.vercel.app/api/mcp, and click Continue.

  2. Keep the detected options, Sign in now and Use Claude's published identity, and click Add.

  3. Claude Desktop asks you to confirm in the browser. Click Continue connecting.

  4. Sign in with your ADMIN_PASSWORD, then click Allow. The consent page shows which app is connecting and where access is sent; only allow it if you just started the connection yourself.

    Claude: Add custom connector, name and URL Claude: Sign in now, Use Claude's published identity Claude Desktop: Continue connecting Consent page: Allow Claude?

Claude Code: run claude mcp add --transport http imap-mcp https://<your-app>.vercel.app/api/mcp, then /mcp → imap-mcp → Authenticate. The status page shows this command ready to copy.

Other clients that support remote MCP servers with OAuth (ChatGPT connectors, Cursor, VS Code, …) work the same way: add the connector URL, sign in, allow.

Database tables and your login are created automatically on the first request. There is no migration step.

Self-host with Docker

Run it on your own server instead of Vercel. The included docker-compose.yml starts three containers: the app, Postgres, and Caddy, which gets a free HTTPS certificate automatically.

You need a server with Docker, ports 80 and 443 open, and a domain (or subdomain) pointing at it. MCP clients like claude.ai only connect over HTTPS.

git clone https://github.com/harrywang/imap-mcp.git
cd imap-mcp
cp .env.example .env

Edit .env:

  • Fill in MAIL_1, MAIL_1_PASSWORD, ADMIN_PASSWORD and BETTER_AUTH_SECRET as in step 3.
  • Uncomment and set DOMAIN (for example mail-mcp.example.com) and POSTGRES_PASSWORD (openssl rand -hex 16).
  • Delete the DATABASE_URL and APP_URL lines. Docker Compose sets both from DOMAIN and POSTGRES_PASSWORD.
  • Put any value containing $ in single quotes, like MAIL_1_PASSWORD='pa$word'. Docker Compose otherwise treats $ as a variable and silently cuts the value.

Then start it:

docker compose up -d

Open https://<your-domain>, sign in, and connect your MCP client to https://<your-domain>/api/mcp, as in step 5. Database tables are created on first start, and Postgres data persists in a Docker volume.

To update: git pull && docker compose up -d --build.

Without Docker. Any server with Node.js 24 and Postgres works: pnpm install && pnpm build && pnpm start, with DATABASE_URL and APP_URL (your public HTTPS URL) set. Put it behind an HTTPS reverse proxy that sets the real client IP in X-Forwarded-For (Caddy and nginx do), and don't expose port 3000 directly, since the login rate limit relies on that header. If the server can't reach its own public URL, set INTERNAL_URL=http://localhost:3000.

Environment variables

VariableRequiredNotes
MAIL_1yesMailbox address. IMAP and SMTP servers are detected from it.
MAIL_1_PASSWORDyesMailbox password, or an app password (see below).
ADMIN_PASSWORDyesPassword for signing in to this app. Must be at least 12 characters; if it's shorter, the app shows a "Finish setup" page and won't let agents connect.
BETTER_AUTH_SECRETyesRandom secret. Rotating it invalidates all sessions and tokens.
DATABASE_URLautoSet by the Neon integration on Vercel, or by Docker Compose. Any Postgres connection string works.
APP_URLself-hostYour public HTTPS URL. Set automatically on Vercel and by Docker Compose (from DOMAIN).
INTERNAL_URLnoHow the server reaches itself to fetch its token-signing keys, when it can't reach its own public URL. Docker Compose sets http://localhost:3000.
ADMIN_EMAILnoLogin username, prefilled on the sign-in page. Defaults to admin@imap-mcp.local. No mail is sent to it.
ATTACHMENT_MAX_RESULT_MBnoLargest image or original file read_attachment returns, in MB. Default 3, which fits Vercel's response limit; self-hosted can go higher.
SEND_LIMIT_PER_HOURnoMax emails each mailbox can send per hour. Default 10.
ALLOW_SENDnofalse removes send_draft, so agents can only save drafts. Default: sending approved drafts is allowed.
MAIL_<n>, MAIL_<n>_PASSWORDnoMore mailboxes: MAIL_2, MAIL_3, …
MAIL_<n>_LABELnoInternal label agents use to pick the mailbox, like work, gmail or yahoo. Recipients never see it. Must be unique. You can always pick a mailbox by its address or number too.
MAIL_<n>_NAMEnoSender name recipients see in the From line, like Harry Wang. Not used to pick mailboxes, so several mailboxes can share it. Without it, mail goes out as the bare address.
MAIL_<n>_USERNAMEnoIMAP/SMTP login, if it differs from the address.
MAIL_<n>_IMAP_HOST / _IMAP_PORT / _SMTP_HOST / _SMTP_PORTnoOverride detection. Port 993/465 use TLS; other ports use STARTTLS or plain.

After changing any variable in Vercel (adding a mailbox, setting ALLOW_SEND, …), redeploy: Deployments → ⋯ on the latest one → Redeploy. A running deployment keeps the values it was built with.

Add more mailboxes

  1. In Vercel, open your project and go to Settings → Environment Variables → Add Environment Variable.
  2. Add MAIL_2 (the address) and MAIL_2_PASSWORD. Use the Secret type so the values can't be read back. For a third mailbox use MAIL_3, and so on, up to 20.
  3. Click Redeploy in the prompt that appears (or Deployments → ⋯ → Redeploy), then Redeploy again to confirm.

Optionally give each mailbox two names, which do different jobs:

VariableWhat it's forExample
MAIL_2_LABELInternal label: what you call the mailbox when talking to the agent ("check my paperfox support inbox"). Recipients never see it.paperfox support
MAIL_2_NAMESender name: what recipients see in the From line of mail you send.Harry Wang

The status page then lists every mailbox with its connection test. Connected agents pick up the new mailbox on their next request; there's no need to reconnect.

Vercel project Settings: Environment Variables Add MAIL_2 and MAIL_2_PASSWORD as Secret Prompt: Redeploy Redeploy dialog

Mailbox passwords

Many providers don't accept your normal password over IMAP. Instead you create an app password: a separate password for one app that only gives mail access and can be revoked on its own without changing your real password.

ProviderWhat to put in MAIL_<n>_PASSWORD
GmailAn app password (turn on 2-Step Verification first): myaccount.google.com/apppasswords
iCloudAn app-specific password: account.apple.com → Sign-In and Security → App-Specific Passwords
FastmailAn app password with IMAP/SMTP access: Settings → Privacy & Security
OthersUse an app password if your provider offers one, otherwise your normal mailbox password

If the mailbox test on the status page shows an authentication error, this is usually why.

Tools

ToolWhat it does
list_accountsConfigured mailboxes
list_foldersFolders in a mailbox
search_emailsSearch by text, from, to, subject, date range, unread. Newest first.
read_emailHeaders, plain-text body, numbered attachment list. Doesn't mark as read.
read_attachmentOpens one attachment. PDF, Word, Excel/CSV, text, HTML, calendar invites and attached emails come back as text, and images as images, so any MCP client can use them. include_original also returns the original file for clients that handle files. Up to 15 MB; other file types (ZIP, …) aren't opened.
create_draftSaves to Drafts, threaded when replying. Replies come from the mailbox the original was read in.
move_emailMove to another folder (Archive, Trash, …)
mark_readMark read or unread
send_draftSends a draft from create_draft, exactly as saved, after you approve it in the chat. The call must repeat the draft's recipients, subject and full body, so your client's approval prompt shows the whole email. Saves a copy to Sent and removes the draft. Max 10 per mailbox per hour. Not available with ALLOW_SEND=false.

When an attachment can't be read, read_attachment says so plainly, ending with a "Tell the user: …" message, and returns an error when nothing usable came back. That covers scanned PDFs (pictures of pages, no text), password-protected or damaged files, unsupported types like ZIP, files over 15 MB, text that was cut off, and files that take more than 20 seconds to process.

Every tool takes an account (address, label or number) and every result says which mailbox it came from.

With several mailboxes, the server keeps them apart:

  • search_emails and list_folders default to the first mailbox when account is left out.
  • read_email, move_email, mark_read, create_draft and send_draft refuse to run without account. UIDs only mean something inside one mailbox, and mail must go out from the right address. The error tells the agent to ask you which mailbox you mean.
  • A reply has to pass both the original's UID and its Message-ID (from read_email). If they don't match in the chosen mailbox, which happens when a UID from one mailbox is used in another, nothing is saved or sent.

Security and privacy

Who can get in

  • The MCP endpoint (/api/mcp) accepts only OAuth access tokens issued by this app and bound to this exact URL.
  • There's a single account, and sign-up is disabled. Sign-in is rate-limited to 5 attempts per minute, stored in the database so the limit holds across serverless instances.
  • Every new client goes through the consent page, which shows where it's from.
  • To cut off access: change BETTER_AUTH_SECRET and redeploy. Every token and session stops working, and every agent has to log in again. Changing ADMIN_PASSWORD changes your login and signs out browser sessions.

What happens to your mail

  • Nothing is stored. Each tool call connects to your mail server, does its job and disconnects. The database holds only your login, OAuth clients and tokens, and rate-limit counters. No message content, addresses or subjects.
  • Nothing is logged or tracked. The app doesn't log mail content and has no analytics.
  • Your agent sees what it reads. Messages and attachments returned by search_emails, read_email and read_attachment go to the agent you connected, so its provider's privacy policy applies to that content. Attachments are converted on your server as they're read and never stored.
  • Reading doesn't change anything. read_email leaves messages unread.

How sending works

  1. The agent saves the message to your Drafts folder with create_draft and shows you the full draft: From, To, Cc, Bcc, subject and body.
  2. You approve it in the chat. Clients like Claude also ask before running send_draft, and the prompt shows the recipients, subject and full body. Don't set it to always-allow.
  3. send_draft sends that exact draft. If the draft was edited or replaced, or the recipients, subject or body don't match what you approved, nothing is sent.
  4. A copy goes to Sent and the draft is removed.

Each mailbox can send at most 10 emails an hour (SEND_LIMIT_PER_HOUR). There's no way to send arbitrary text or forward messages. Set ALLOW_SEND=false for drafts only.

The remaining risk: the mailbox password sits in Vercel's environment variables, which are encrypted at rest. An app password limits the damage if they ever leak: it only opens mail and you can revoke it without changing your real password.

Local development

Only needed if you want to run or change the code yourself. You need Node.js, pnpm and a local Postgres.

createdb imap_mcp
cp .env.example .env.local   # fill in values (APP_URL is only needed locally)
pnpm install
pnpm dev

To check the whole OAuth + MCP flow from the command line (the same steps an MCP client goes through), run the smoke test with your ADMIN_PASSWORD. It calls list_accounts by default, or any tool you name:

PASSWORD=your-admin-password node scripts/smoke-test.mjs
PASSWORD=your-admin-password node scripts/smoke-test.mjs search_emails '{"limit":3}'

Credits

Logo: Email Mail from SVG Repo, CC0 license.

License

MIT

No installation packages available.

Remote

streamable-http
https://{host}/api/mcp