# spacemail-mcp

An MCP server that gives Claude access to one or more Spacemail (Spaceship business
email) mailboxes.

## Why it works this way

Spaceship's public API at docs.spaceship.dev covers domains, DNS and SellerHub. It has no
mailbox endpoints, so there is nothing to wrap for mail. Spacemail does expose standard
IMAP and SMTP, enabled by default, so this server talks to those directly:

| Protocol | Host | Port | Encryption |
|---|---|---|---|
| IMAP | mail.spacemail.com | 993 | SSL |
| SMTP | mail.spacemail.com | 465 | SSL |

Username is the full Spacemail address, password is that mailbox's own password.

## Tools

| Tool | What it does |
|---|---|
| `list_accounts` | Which mailboxes are configured, and which is the default. |
| `test_connection` | Verifies credentials. One mailbox, or all of them at once. |
| `list_folders` | Every folder with message and unread counts. |
| `search_messages` | Filter by from, to, subject, body, date, unread. Newest first. |
| `read_message` | One message: headers, plain-text body, attachment list. |
| `set_read_state` | Mark read or unread. |
| `move_message` | Move between folders, including to Trash. |
| `save_draft` | Compose and save to Drafts without sending. |
| `send_message` | Send over SMTP. Off unless explicitly enabled per account. |

Every tool takes an optional `account`. With one mailbox configured it is ignored. With
several, omitting it uses the default. `search_messages` also accepts `account: "*"` to
search every mailbox in one call.

Two deliberate omissions:

- **No permanent delete.** The worst any tool can do is move a message to Trash, which
  you can undo by moving it back.
- **Sending is opt-in, per account.** `send_message` refuses unless `allowSend` is true
  for that specific mailbox. Leave it off and use `save_draft`, so a human presses send.

## Setup

### 1. Install

Requires Node.js 18 or later.

```
cd path/to/spacemail-mcp
npm install
```

### 2. Create accounts.json

Copy `accounts.example.json` to `accounts.json` and fill it in. This file is gitignored.

```json
{
  "accounts": [
    {
      "label": "personal",
      "user": "you@example.com",
      "password": "the-mailbox-password",
      "default": true,
      "fromName": "Your Name"
    },
    {
      "label": "work",
      "user": "hello@example.org",
      "password": "the-other-password"
    }
  ]
}
```

Per-account fields: `label` (what you call it in chat), `user`, `password`, and optionally
`default`, `fromName`, `allowSend`, `imapHost`, `imapPort`, `smtpHost`, `smtpPort`.

Labels must be unique. If you omit `label` it is derived from the address, so two mailboxes
on different domains with the same local part (`info@a.com` and `info@b.com`) both become
`info` and the server will refuse to start. Give them explicit labels.

Passwords come from Spacemail Manager: find the subscription, click the three dots next to
the mailbox, choose IMAP/POP3/SMTP. Reset the password there if you no longer have it.

### 3. Register with the Claude desktop app

Settings, then Developer, then Edit Config, which opens
`%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "spacemail": {
      "command": "node",
      "args": ["C:\\path\\to\\spacemail-mcp\\index.js"],
      "env": {
        "SPACEMAIL_CONFIG": "C:\\path\\to\\spacemail-mcp\\accounts.json"
      }
    }
  }
}
```

Backslashes must be doubled in JSON. Restart the app fully from the system tray afterwards.

Or with the Claude Code CLI:

```
claude mcp add --transport stdio spacemail ^
  --env SPACEMAIL_CONFIG="C:\path\to\spacemail-mcp\accounts.json" ^
  -- node "C:\path\to\spacemail-mcp\index.js"
```

### 4. Verify

Ask Claude to run `test_connection` with no account argument. It tests every mailbox and
reports each one as ok or failed independently, so one bad password does not hide the rest.

## Other ways to supply credentials

Checked in this order. The first one present wins.

**1. Config file (recommended for two or more mailboxes)**

`SPACEMAIL_CONFIG` pointing at the JSON file above.

**2. Numbered environment variables**

`SPACEMAIL_1_USER`, `SPACEMAIL_1_PASSWORD`, `SPACEMAIL_1_LABEL`, `SPACEMAIL_1_DEFAULT`,
`SPACEMAIL_1_ALLOW_SEND`, `SPACEMAIL_1_FROM_NAME`, then `SPACEMAIL_2_*` and so on, up to 20.

**3. Single account**

`SPACEMAIL_USER` and `SPACEMAIL_PASSWORD`, plus optional `SPACEMAIL_IMAP_HOST`,
`SPACEMAIL_IMAP_PORT`, `SPACEMAIL_SMTP_HOST`, `SPACEMAIL_SMTP_PORT`, `SPACEMAIL_ALLOW_SEND`,
`SPACEMAIL_FROM_NAME`.

## Troubleshooting

**Server will not start.** It exits with a specific message on stdout: unreadable config
file, missing password, duplicate label, or no mailboxes configured at all. Run
`node index.js` in the folder directly to see it.

**One mailbox fails, others work.** Run `test_connection` with no arguments. Each account
reports separately. The usual cause is the username not being the full email address, or
IMAP being switched off for that mailbox in Spacemail Manager.

**Server shows as disconnected in Claude.** MCP subprocesses launch with a different
environment than your terminal, so `node` may not be on the path. Use the absolute path to
node.exe, which `where node` gives you.

**Nothing found by `search_messages`.** Folder paths are case sensitive and vary. Run
`list_folders` first and use the exact `path` value it returns.

**Sending rejected.** `allowSend` must be true for that specific account. Spacemail also
caps outbound volume per plan.