# imap-mail-mcp

An MCP (Model Context Protocol) server that lets Claude read, search, and send
email over standard IMAP/SMTP. Works with any provider that supports
username/password authentication over IMAP and SMTP — IONOS, GMX, Web.de, and
most other non-Gmail/non-Microsoft providers.

## Tools

| Tool | Description |
| --- | --- |
| `list_mailboxes` | List all folders (INBOX, Sent, Drafts, Trash, custom folders, ...) |
| `list_messages` | List the most recent messages in a mailbox |
| `search_messages` | Search by sender, recipient, subject, body text, or date range |
| `get_message` | Fetch the full text/HTML body and attachment metadata of one message |
| `mark_message` | Mark a message as read/unread or flagged/unflagged |
| `send_mail` | Send a new email or reply to an existing one |

## Setup

1. Install dependencies and build:

   ```bash
   npm install
   npm run build
   ```

2. Copy `.env.example` to `.env` and fill in your mailbox credentials (only
   needed for local testing via `npm start` — see below for how credentials
   are supplied when running through Claude Desktop).

3. If your provider supports 2FA / app-specific passwords, use one of those
   instead of your main account password.

## Using it with Claude Desktop

Add an entry to your `claude_desktop_config.json`
(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "imap-mail": {
      "command": "node",
      "args": ["/absolute/path/to/imap-mail-mcp/dist/index.js"],
      "env": {
        "EMAIL_USER": "you@example.com",
        "EMAIL_PASSWORD": "your-password-or-app-password",
        "IMAP_HOST": "imap.example.com",
        "IMAP_PORT": "993",
        "SMTP_HOST": "smtp.example.com",
        "SMTP_PORT": "587"
      }
    }
  }
}
```

Restart Claude Desktop fully (quit and reopen) after editing the config.

## Environment variables

| Variable | Required | Default | Notes |
| --- | --- | --- | --- |
| `EMAIL_USER` | yes | — | Mailbox login (usually your email address) |
| `EMAIL_PASSWORD` | yes | — | Password or app-specific password |
| `IMAP_HOST` | yes | — | e.g. `imap.ionos.de` |
| `IMAP_PORT` | no | `993` | IMAP over implicit TLS |
| `SMTP_HOST` | yes | — | e.g. `smtp.ionos.de` |
| `SMTP_PORT` | no | `587` | STARTTLS; use `465` for implicit TLS |

For backwards compatibility, `IONOS_EMAIL`, `IONOS_PASSWORD`,
`IONOS_IMAP_HOST`, `IONOS_IMAP_PORT`, `IONOS_SMTP_HOST`, and
`IONOS_SMTP_PORT` are also accepted as aliases.

## Security notes

- Credentials are only ever read from environment variables. They are never
  logged, written to disk, or included in any response text beyond what the
  IMAP/SMTP server itself returns.
- Claude Desktop's `mcpServers` config stores the `env` block in plain text
  on your machine. Anyone with access to your user account can read it, same
  as any other locally saved password.
- `.env` is git-ignored — never commit real credentials.

## Requirements

- Node.js 18+