TheSameAbramovych/qmailing-mcp-server

Two ways to plug an AI agent into QMailing — pick the one that matches
your client.
| Client | Recommended setup |
|--------------------------------|--------------------------------------------|
| **Claude.ai** (web / mobile) | Custom Connector — one URL, no token, OAuth handles auth |
| Claude Desktop, Cursor, Continue, Zed, custom CLIs | @qmailing/mcp-server — npm package + API token |
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 .
2. Go to **Settings → Developers** — copy the **Server URL** at the top:
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 .
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
Pin a specific version (e.g. @qmailing/mcp-server@0.3.5) if you don't want auto-upgrades.
Claude Code
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:
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 |