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:

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

Related MCP server: IMAP MCP Server

Tools

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.

{
  "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:

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