@qmailing/mcp-server

@qmailing/mcp-server

Model Context Protocol server for qmailing.

Lets AI agents — Claude Desktop, Cursor, Continue, Zed, anything that speaks MCP — read and modify your qmailing mailboxes, custom domains, and DNS settings on your behalf.

Requirements

• A qmailing account on the PRO tier or higher (the public API is gated on PRO+).
• Node.js 18.17 or later.
• An MCP-compatible client (e.g. Claude Desktop).

Setup

1. Generate an API token

• Sign in at https://qmailing.com.

• Go to Settings → Developers.

• Click New token, give it a label (e.g. "Claude Desktop"), pick the scopes you want the agent to have, and copy the qm_live_… value when it's shown.

  The token only appears once. If you lose it, generate a fresh one.

2. Build the server locally

The @qmailing/mcp-server package is not yet published to npm. Until it ships there, install it from the qmailing monorepo:

git clone https://gitlab.com/qmailing/qmailing-web.git   # or however you got the source
cd qmailing-web/mcp
npm install
npm run build

npm run build produces dist/server.js — the executable the MCP client will spawn.

3. Wire it into your MCP client

You point the client at the absolute path to dist/server.js. Two patterns:

Pattern A — direct node invocation (works everywhere)

{
  "mcpServers": {
    "qmailing": {
      "command": "node",
      "args": ["/absolute/path/to/qmailing-web/mcp/dist/server.js"],
      "env": {
        "QMAILING_API_TOKEN": "qm_live_your_token_here"
      }
    }
  }
}

On Windows use forward slashes or escape the backslashes: "C:/Users/you/qmailing-web/mcp/dist/server.js".

Pattern B — npm link once, then call by binary name

cd qmailing-web/mcp
npm link        # installs the `qmailing-mcp` shim onto your PATH

{
  "mcpServers": {
    "qmailing": {
      "command": "qmailing-mcp",
      "env": {
        "QMAILING_API_TOKEN": "qm_live_your_token_here"
      }
    }
  }
}

Where the MCP config lives

• Claude Desktop
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
• Claude Code: claude mcp add writes to ~/.claude.json. To register manually:

  claude mcp add qmailing --command node --args "/absolute/path/to/qmailing-web/mcp/dist/server.js" --env QMAILING_API_TOKEN=qm_live_…
  

• Cursor / Continue / Zed: any client that supports stdio MCP servers — same command + args + env shape.

After editing the config, restart the client. The qmailing tools should appear in the tools menu (the wrench icon in Claude Desktop, similar in others).

When will npx @qmailing/mcp-server work?

It will, once the package is published to the public npm registry. The package.json here is already shaped for publish — npm publish --access public from inside this directory pushes it. Until that happens, use Pattern A above.

Tools

Tool	What it does	Required scope
qmailing_list_mailboxes	List every mailbox on the account	mailboxes:read
qmailing_get_mailbox	Fetch one mailbox by id	mailboxes:read
qmailing_create_mailbox	Create a new mailbox under qmailing.com or a verified custom domain	mailboxes:write
qmailing_list_domains	List custom domains and verification state	domains:read
qmailing_get_dns_records	DNS-records checklist for one domain	domains:read

Configuration

Env var	Default	Purpose
QMAILING_API_TOKEN	required	Bearer token from /settings/developers
QMAILING_API_URL	https://qmailing.com	Override for self-hosted / staging deployments

Security notes

• The token authenticates as your full qmailing account within the scopes you granted. Treat it like a password.
• Tokens are revocable and the FE shows the prefix + last-used timestamp, so you can identify a compromised one and kill it from /settings/developers.
• Plan downgrades disable existing tokens immediately — the API re-checks the plan on every request, no per-token revocation needed.
• The MCP server runs locally on your machine; your token never leaves the process you launched. Only the qmailing API itself sees it.

Development

The package source is maintained in the qmailing monorepo. To work on it locally with a checkout, install deps inside the mcp/ directory and build:

cd mcp
npm install
npm run build
QMAILING_API_TOKEN=qm_live_test_token npm start

For bug reports or questions, reach us through the contact form at qmailing.com/contact.

License

MIT