email-mcp

Local IMAP/SMTP MCP server. Lets Claude read, search, draft, send, flag, and move mail across multiple IMAP mailboxes. Credentials stay on your machine.

Built for simply.com mailboxes first; works with any IMAP/SMTP provider.

What it can do

• list_accounts, list_folders
• list_recent, list_unread, list_flagged, search, get_message
• mark_read, mark_unread, flag, unflag, move, delete (to Trash)
• create_draft, send_message

All tools take an account_id as their first argument, so the same server handles multiple mailboxes.

One-time setup

1. Install Python deps

From a terminal in this directory:

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

(You can skip the venv and use a global Python if you prefer — run.bat falls back to the system python if .venv doesn't exist.)

2. Configure your account

Copy .env.example to .env and fill in your simply.com mailbox password:

copy .env.example .env

Then open .env in a text editor and replace replace-me under FORTEA_PASSWORD= with your actual mailbox password. If your simply.com account has 2FA enabled, generate an app password in the simply.com control panel and use that instead.

Verify the IMAP/SMTP host values in .env against the simply.com control panel under Email → Settings. The defaults (imap.simply.com:993, send.simply.com:465) are the common ones but worth double-checking.

3. Test it from the command line

.venv\Scripts\python server.py

The server will print nothing and wait on stdin — that's the MCP protocol. Hit Ctrl-C. If you see an import error or credential error, fix it before registering with Claude.

4. Register with Claude desktop

Edit your Claude desktop config:

%APPDATA%\Claude\claude_desktop_config.json

Add (or merge) this block:

{
  "mcpServers": {
    "email": {
      "command": "C:\\Users\\sigur\\email-mcp\\run.bat"
    }
  }
}

If you move the folder, update the path above. (You'll probably want to move it out of the session outputs dir into something more permanent like %USERPROFILE%\email-mcp\ — see "Make it permanent" below.)

Restart Claude desktop. The email server's tools should appear in chat.

5. Make it permanent (recommended)

The session outputs folder is meant to be temporary. Move the project to a stable location:

move "%APPDATA%\Claude\local-agent-mode-sessions\...\outputs\email-mcp" "%USERPROFILE%\email-mcp"

Then update the command path in claude_desktop_config.json to match.

Adding more accounts

In .env:

1. Add the prefix to the list:

   EMAIL_ACCOUNTS=fortea,bogholderi,expense
   

2. Add a matching block for each:

   BOGHOLDERI_EMAIL=bogholderi@fortea.dk
   BOGHOLDERI_USERNAME=bogholderi@fortea.dk
   BOGHOLDERI_PASSWORD=...
   BOGHOLDERI_IMAP_HOST=imap.simply.com
   BOGHOLDERI_IMAP_PORT=993
   BOGHOLDERI_SMTP_HOST=send.simply.com
   BOGHOLDERI_SMTP_PORT=465
   

Restart the MCP server (close & reopen Claude desktop, or kill the run.bat process) to pick up new accounts.

Security notes

• .env is gitignored. Don't commit it.
• Credentials live only on this machine, in this folder.
• The server runs locally via stdio — nothing is exposed on a network port.
• For better security, replace the .env loader with Windows Credential Manager (out of scope for v1).
• send_message actually sends mail. Treat it accordingly when working with Claude: confirm recipient and body before approving the send.

Known limitations

• Microsoft 365 IMAP requires OAuth (XOAUTH2) and Azure AD admin consent — not supported in v1. Use the official M365 connector once admin consent is granted.
• No attachment send in v1 (drafts/send are text body only).
• No threading view — messages are returned as flat lists with message_id for client-side threading.
• IMAP UIDs are folder-scoped. If you move a message, its UID changes.