IMAP MCP

An MCP server that gives Claude read, manage and send access to any IMAP mailbox, for the mail that Google and Microsoft connectors do not cover: hosting company mailboxes (xneelo, cPanel, Plesk), self hosted Dovecot, anything that speaks plain IMAP and SMTP.

Runs locally over stdio. Your password stays in a local .env file, and mail goes directly from this machine to your mail server.

What Claude gets

Safety rules built in

• Reading never marks mail as read. Every fetch uses BODY.PEEK and folders open read only, so Claude browsing the mailbox does not change its state. get_message(mark_seen=True) is the only exception and has to be asked for.

• Sending and permanent deletion take two steps. The first call returns the exact message or the exact target plus a confirmation_token and does nothing. Only a second call with commit=True and that token acts. Change any argument between the two calls and the token stops matching.

• Delete means Trash. delete_messages moves to the Trash folder unless you pass permanent=True.

• Per account read_only. Set "read_only": true on an account and every write tool refuses, while reading keeps working.

• Sent mail is filed. SMTP does not copy what it sends, so after a send the same bytes are appended to the Sent folder, where your normal mail client expects them.

• Attachments go to disk, never into the conversation.

Setup

1. Install:

   uv venv --python 3.12
   uv pip install -e ".[dev]"

2. Copy accounts.example.json to accounts.json and fill in your mail server details. Ask your host for the IMAP and SMTP settings if you do not have them. Passwords do not go in this file.

3. Copy .env.example to .env and add one password per account. The variable name is the account name, uppercased, with anything that is not a letter or digit turned into an underscore: account work reads IMAP_PASSWORD_WORK. Add SMTP_PASSWORD_<NAME> only if the SMTP password differs.

4. Prove the account works before wiring it in:

   .venv\Scripts\python.exe scripts\smoke.py

5. Register the server with Claude Code:

   claude mcp add --scope user imap -- "C:\Claude Projects\IMAP MCP\.venv\Scripts\python.exe" -m imap_mcp.server

   Restart Claude Code and check /mcp.

Account fields

Sent, Trash and Drafts are found from the server's SPECIAL-USE flags, falling back to the usual names including the Dovecot style INBOX.Sent.

Shared hosting and certificates

Hosts like xneelo point mail.yourdomain.co.za at a shared server whose certificate is issued for the server's own name, so strict TLS verification fails on the vanity hostname even though the connection is fine. Find the real server name and use that instead:

python -c "import socket; print(socket.gethostbyaddr(socket.gethostbyname('mail.yourdomain.co.za')))"

That returns something like www12.cpt3.host-h.net, which its certificate does cover. The tradeoff is that if the host migrates your mailbox to another server, the hostname changes and login starts failing: rerun the line above and update accounts.json. The alternative is keeping the vanity hostname with "verify_tls": false.

Not supported

OAuth2, so Gmail and Microsoft 365 are out of scope: they have first party connectors already. Password authentication over TLS only. Gmail with an app password does work if you want it here anyway.

Tests

.venv\Scripts\python.exe -m pytest          # 35 unit tests, no network

End to end against a throwaway mail server in Docker, which exercises all 12 tools including sending, moving and permanent deletion without touching a real mailbox:

docker run -d --rm --name imapmcp-greenmail -p 3143:3143 -p 3025:3025 ^
  -e GREENMAIL_OPTS="-Dgreenmail.setup.test.all -Dgreenmail.hostname=0.0.0.0 -Dgreenmail.auth.disabled" ^
  greenmail/standalone:2.1.0
.venv\Scripts\python.exe scripts\e2e_greenmail.py
docker stop imapmcp-greenmail