# 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:

```json
{
  "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.