QMailing — Model Context Protocol

Two ways to plug an AI agent into QMailing — pick the one that matches your client.

The two paths give the same tool surface — qmailing_list_mailboxes, qmailing_send_email, etc. They differ only in how the client authenticates: OAuth flow (browser) vs static bearer token (CLI / config).

🔗 Claude.ai Custom Connector (recommended)

Works with the Claude.ai web app and Claude mobile. No package install, no token management — the OAuth flow brokers per-grant scope consent and rotates refresh tokens automatically.

Setup (60 seconds)

1. Sign in at https://qmailing.com.
2. Go to Settings → Developers — copy the Server URL at the top:

   https://qmailing.com/mcp
   

3. Open Claude.ai → Settings → Connectors → Add custom connector.
4. Paste the server URL into the form. Claude.ai redirects you back to QMailing to sign in.
5. Approve the requested scopes (Read mailboxes / Send emails / etc.) — the consent screen lists each one with a description before you click Allow.
6. Done. Claude.ai shows the QMailing tools in its tool tray on every chat.

Revoking access

• From Claude.ai: Settings → Connectors → QMailing → Remove.
• From QMailing: signing out of every device (Settings → Profile → Sign out everywhere) invalidates outstanding tokens immediately.

What scopes mean

Same vocabulary as the API token scopes below. You consent to each one separately on first connection; granted scopes persist across re-grants until you revoke.

📦 Legacy MCP clients (npm package + API token)

For clients that don't speak OAuth Custom Connectors yet — Claude Desktop, Cursor, Continue, Zed, and any CLI MCP client.

Requirements

• A QMailing account on the PLUS tier or higher (the public API is gated on PLUS).
• Node.js 18.17 or later.

Setup

1. Generate an API token

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

2. Go to Settings → Developers.

3. 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. Wire it into your MCP client

The package is published on the public npm registry — npx pulls the latest version on first run, no manual checkout required.

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "qmailing": {
      "command": "npx",
      "args": ["-y", "@qmailing/mcp-server"],
      "env": {
        "QMAILING_API_TOKEN": "qm_live_your_token_here"
      }
    }
  }
}

Pin a specific version (e.g. @qmailing/mcp-server@0.3.4) if you don't want auto-upgrades.

Claude Code

claude mcp add qmailing -- npx -y @qmailing/mcp-server
# Add the env var separately or supply via a wrapper script.

Cursor / Continue / Zed / others

Any MCP client that supports stdio servers takes the same command + args + env shape. Restart the client after editing its config — the QMailing tools appear in the tools menu (the wrench icon in Claude Desktop, similar in others).

Local development checkout

Contributors can run from a checkout instead of npm. Build + point the client at the absolute path:

cd qmailing-web/mcp
npm install
npm run build       # produces dist/server.js

{
  

... [View full README on GitHub](https://github.com/thesameabramovych/qmailing-mcp-server#readme)