mx-route-mcp

A Model Context Protocol (MCP) server for the MXroute email hosting API. Connect it to an MCP client such as Claude Desktop, Claude Code or Cursor and manage your MXroute account in plain language: add domains, create mailboxes, set up forwarders, tune spam filtering, look up the DNS records a domain needs, check disk usage, and administer reseller users and packages.

Unofficial. This project is not affiliated with or endorsed by MXroute. It wraps their public REST API.

• Complete. One tool for each of the 43 operations in the MXroute API, kept honest by a test that compares the tool list with the API's operation list.
• Guard rails built in. Every tool carries MCP behaviour hints (read-only / destructive / idempotent) so clients can ask before deleting anything, and destructive tools say so in their description. A read-only mode and per-area toolsets let you hand an assistant only what it needs.
• Private. Your API key lives in the server's environment. By default it is sent only to api.mxroute.com over HTTPS, never logged, and never shown to the model.

Contents

• What you can ask it
• Quick start
• Using it
• How it works
• Configuration
• Resellers
• Tool reference
• Security
• Troubleshooting
• Project status
• Development
• About Maui Growth

What you can ask it

• "Which domains are on my MXroute account, and how many mailboxes does each have?"
• "I want to add example.org. What DNS record do I need to create first?"
• "Create a mailbox support@example.com with a 5 GB quota and forward sales@example.com to me@example.net."
• "Which mailboxes are using the most disk space?"
• "Show me the MX, SPF and DKIM records for example.com."
• "Add *@spam-domain.example to my spam blacklist (account-wide) and raise the spam auto-delete score on example.com to 15."

Quick start

Requirements: Node.js 20 or newer, an MXroute account, and an MCP client.

1. Get your credentials

Create an API key on the MXroute API keys page. The page shows three values; the key is displayed once, so copy it when it is created.

| Variable | What it is | Example | | --- | --- | --- | | MXROUTE_SERVER | Your mail server hostname (the "X-Server" value) | eagle.mxlogin.com | | MXROUTE_USERNAME | Your DirectAdmin username (the "X-Username" value), or reseller\|user — see Resellers | johndoe | | MXROUTE_API_KEY | The complete API key, unchanged, colons included | Mx8d98… |

2. Add the server to your client

The server is started with npx, which downloads and builds it from this repository on first use (this takes a few seconds, once):

npx -y github:MauiGrowth/mx-route-mcp

Claude Desktop — add this to claude_desktop_config.json (Settings → Developer → Edit Config), then restart the app:

{
  "mcpServers": {
    "mxroute": {
      "command": "npx",
      "args": ["-y", "github:MauiGrowth/mx-route-mcp"],
      "env": {
        "MXROUTE_SERVER": "eagle.mxlogin.com",
        "MXROUTE_USERNAME": "your_directadmin_username",
        "MXROUTE_API_KEY": "your_complete_api_key"
      }
    }
  }
}

Claude Code

claude mcp add mxroute \
  --env MXROUTE_SERVER=eagle.mxlogin.com \
  --env MXROUTE_USERNAME=your_directadmin_username \
  --env MXROUTE_API_KEY=your_complete_api_key \
  -- npx -y github:MauiGrowth/mx-route-mcp

Cursor and other clients — Cursor uses the same mcpServers JSON as Claude Desktop (in .cursor/mcp.json). Any client that can launch a stdio MCP server works: run the npx command above with the three environment variables set.

Prefer to build it yourself? Clone the repo, run npm install (this also builds it), and point your client at node /absolute/path/to/mx-route-mcp/dist/index.js instead of npx. That also avoids the first-run build delay.

3. Check it works

MXROUTE_SERVER=eagle.mxlogin.com MXROUTE_USERNAME=you MXROUTE_API_KEY=... \
  npx -y github:MauiGrowth/mx-route-mcp --check

This lists your domains once and prints OK: authenticated to … ; N domains found. Nothing is modified. Then restart your client and ask: "Which domains are on my MXroute account?"

For a fuller read-only check of every list/get tool against your own account, from a clone of this repo:

npm install
MXROUTE_SERVER=eagle.mxlogin.com MXROUTE_USERNAME=you MXROUTE_API_KEY=... npm run smoke:live

It starts the server in read-only mode (write tools are not registered, so nothing can change), calls each read tool, and prints only pass/fail with counts, never domain names or addresses. Reseller tools are reported as skipped on non-reseller accounts.

Using it

Just describe what you want. The assistant picks the tools, fills in the arguments, and tells you what happened. For example:

You: Add a mailbox orders@example.com with a 2 GB quota and forward sales@example.com to it.

Assistant: (calls create_email_account with domain: "example.com", username: "orders", quota: 2048, then create_forwarder with alias: "sales", destinations: ["orders@example.com"]) Done: orders@example.com exists with a 2 GB quota, and mail to sales@example.com now forwards to it.

A few things worth knowing:

• Destructive actions ask first. Deleting a mailbox, domain, forwarder or user, changing a password, or switching a catch-all to blackhole are marked destructive. Most clients show a confirmation prompt for those, and the assistant is told to confirm with you.
• Passwords go through the conversation. If you ask the assistant to create a mailbox, the password is part of your chat. See Security.
• Adding a domain needs proof of ownership. The assistant fetches the verification record (get_domain_verification_key) and asks you to create it at your DNS provider; this server cannot change DNS. After DNS propagates (typically 5–15 minutes) it can add the domain.
• Names are bare. Mailbox and forwarder names are the part before the @; domains are plain names like example.com. Mistakes are rejected with a message the assistant can act on, as are misspelled arguments.
• Spam lists are account-wide. Whitelist/blacklist entries apply to every domain on the account. The domain argument only has to be one you own.

How it works

flowchart LR
    A["MCP client<br/>(Claude Desktop, Cursor, ...)"] -- "stdio, JSON-RPC" --> B["mx-route-mcp<br/>(runs on your machine)"]
    B -- "HTTPS + 3 auth headers" --> C["api.mxroute.com"]
    C --> D["Your MXroute account"]

The server is a small local program. Your MCP client starts it as a child process and talks to it over stdin/stdout; it holds your credentials in its environment and makes HTTPS calls to the MXroute REST API on the assistant's behalf. Nothing is hosted, and nothing is sent anywhere except MXroute.

What happens on a request:

1. Startup. The client launches the server with your environment variables. The server registers its tools (all 43, or fewer if you set MXROUTE_READ_ONLY or MXROUTE_TOOLSETS) and tells the client each tool's name, description, argument schema and behaviour hints (read-only, destructive, idempotent). It starts even without credentials; they are checked on the first call.
2. Tool call. The assistant chooses a tool and arguments. The server validates them against a strict schema: required fields, types, ranges (a send limit of 9600, a spam score of 1–50), and the shapes the API expects. Unknown or misspelled arguments, full email addresses where a name belongs, and URLs where a domain belongs are rejected before anything is sent.
3. Mapping to the API. Each tool is bound to exactly one API operation, for example POST /domains/{domain}/email-accounts. Path parameters are filled from the arguments (URL-encoded, with ./.. rejected) and the remaining arguments become the JSON body.
4. The HTTP call. The server adds the X-Server, X-Username and X-API-Key headers and sends the request with a timeout. It never follows redirects (which could forward your key to another host) and never retries (a retried write could apply twice).
5. The result. The {success, data} envelope is unwrapped; a 204 No Content becomes a plain confirmation message; API errors become readable tool errors with the code, message and field (for example VALIDATION_ERROR on password); any field that looks like a credential is masked; and compact JSON goes back to the assistant. If a write times out, the error says the change may or may not have been applied, so the assistant checks the current state before trying again.

Worked example. The request "create a mailbox orders@example.com with a 2 GB quota" becomes:

// tool call
{ "name": "create_email_account",
  "arguments": { "domain": "example.com", "username": "orders", "password": "…", "quota": 2048 } }

POST https://api.mxroute.com/domains/example.com/email-accounts
X-Server: eagle.mxlogin.com
X-Username: johndoe
X-API-Key: ********
Content-Type: application/json

{ "username": "orders", "password": "…", "quota": 2048 }

Where things live:

| Path | Responsibility | | --- | --- | | src/tools/*.ts | One tool({...}) per API operation: name, description, argument schema, the operation it calls. Grouped by area (domains, mailboxes, spam, quota, reseller). | | src/tools/define.ts | The tool() factory and runTool: fills path parameters, builds the body, derives the MCP hints from the HTTP method (GET = read-only, DELETE = destructive). | | src/client.ts | The HTTP client: auth headers, timeout, no redirects, response unwrapping, error mapping. | | src/config.ts | Reads and validates the environment variables. | | src/server.ts | Registers the tools with the MCP SDK, formats results and errors. | | src/redact.ts | Masks credential-looking fields in responses. | | src/index.ts | The command-line entry point (--check, --tools, --version, stdio server). |

Because a tool declares the operation it calls and the request is built from that declaration, a tool cannot claim to do one thing and send another. A test calls every tool and asserts the exact method, path and body it produces, and another compares the tool list with the API's operation list.

Configuration

| Variable | Default | Purpose | | --- | --- | --- | | MXROUTE_SERVER | – (required) | Mail server hostname. A pasted https://… URL is accepted and trimmed. | | MXROUTE_USERNAME | – (required) | DirectAdmin username, or reseller\|user. | | MXROUTE_API_KEY | – (required) | API key password. | | MXROUTE_READ_ONLY | false | true registers only the read-only tools; the write tools do not exist for the assistant at all. Accepts true/false, 1/0, yes/no, on/off; anything else is a startup error rather than silently leaving writes enabled. | | MXROUTE_TOOLSETS | all | Comma-separated subset of toolsets (account, domains, pointers, mailboxes, forwarders, spam, dns, catchall, quota, reseller_users, reseller_packages), for example domains,mailboxes,dns. Unknown names are a startup error. | | MXROUTE_TIMEOUT_MS | 30000 | Per-request timeout (1000–300000). | | MXROUTE_API_URL | `https://api.mxroute.co