Provides tools for interacting with a self-hosted Listmonk instance, including managing lists, subscribers, campaigns, templates, bounces, system settings, logs, SMTP tests, and sending transactional email.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@listmonk-mcp how many subscribers do I have, and which lists are they on?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for self-hosted Listmonk. Lists, subscribers, campaigns, templates, bounces and transactional email as MCP tools.
Status: Phase 1 tools are implemented and tested against Listmonk v6.1.0 (selftest, read tools, subscriber write round-trip, read-only mode).
Node.js 18+
Listmonk v6.x with an API user (Admin -> Users -> API user)
Related MCP server: listmonk-mcp-bridge
npm install
npm run build
cp .env.example .env # fill in LISTMONK_URL, LISTMONK_API_USER, LISTMONK_API_TOKEN
npm run selftest # verifies URL, credentials and permissions before you register the serverVariable | Required | Default | Purpose |
LISTMONK_URL | yes | Base URL of the instance, no /api | |
LISTMONK_API_USER | yes | API user name | |
LISTMONK_API_TOKEN | yes | API token | |
LISTMONK_MCP_READONLY | no | false | true = write and delete tools are not registered |
MCP_TRANSPORT | no | stdio | stdio or http |
MCP_HTTP_PORT | no | 3100 | HTTP port |
MCP_HTTP_TOKEN | http only | At least 24 characters |
System: listmonk_status, listmonk_dashboard_counts, listmonk_logs, listmonk_settings_get (secrets redacted), listmonk_smtp_test
Lists: lists_list, list_get, list_create, list_update, list_delete
Subscribers: subscribers_search, subscriber_get, subscriber_create, subscriber_update, subscribers_lists_change, subscriber_delete
Campaigns: campaigns_search, campaign_get, campaign_create, campaign_update, campaign_set_status, campaign_test_send, campaign_delete
Templates: templates_list, template_get, template_create, template_update, template_delete
Bounces: bounces_search, bounce_get, bounce_delete
Transactional: tx_send
Read-only mode registers 14 tools (all read tools). Read-write registers 32.
Note: campaign_set_status with "running" sends email to every recipient immediately.
The full planned set is in TOOL-SPEC.md.
Credentials come from environment variables only.
Settings output redacts any key containing pass, secret, token, key or cred.
Over HTTP, the /mcp/ URL is itself the secret. Treat it like a password.
MIT
Delete a bounce record by id. Does not change the subscriber's status; use subscriber_update to re-enable a subscriber.
Inputs: id (required).
One bounce record by id.
Inputs: id (required).
Recorded bounces, newest first. Filter by bounce type (soft, hard, complaint) and campaign.
Inputs: page, type, per_page, campaign_id.
Create a campaign as a draft. Nothing is sent until campaign_set_status moves it to running or scheduled.
Inputs: name (required), subject (required), list_ids (required), from_email (required), +6 more.
Permanently delete a campaign and its view and click statistics. Listmonk rejects deletion of running campaigns.
Inputs: id (required).
One campaign by id, including body, lists, and send statistics.
Inputs: id (required).
Start, schedule, pause, resume, or cancel a campaign. 'running' SENDS EMAIL to all recipients immediately. 'scheduled' sends at send_at. Confirm the recipient lists and body before using.
Inputs: id (required), status (required).
List campaigns. Filter by status (draft, scheduled, running, paused, cancelled, finished) and optional query text.
Inputs: page, query, status, per_page.
Send a test copy of a campaign to up to 10 email addresses. Sends real mail to those addresses.
Inputs: id (required), emails (required).
Update a campaign. Only the fields you pass change. Listmonk only allows edits while the campaign is a draft, scheduled, or paused.
Inputs: id (required), body, name, tags, +6 more.
Create a mailing list. type is 'public' or 'private'; optin is 'single' or 'double'.
Inputs: name (required), tags, type, optin, +1 more.
Permanently delete a mailing list by id. Subscriptions to it are removed; subscriber records are kept.
Inputs: id (required).
One mailing list by id.
Inputs: id (required).
Totals across the instance: subscribers by status, lists, campaigns, and messages.
Inputs: no named parameters.
Recent Listmonk application log lines (ring buffer, not persisted).
Inputs: no named parameters.
Instance settings. Passwords, keys, and tokens are replaced with [redacted] before being returned.
Inputs: no named parameters.
Opens a connection to a configured SMTP server and sends a test email to the given address. Sends real mail through the instance's SMTP settings.
Inputs: email (required), smtp_index (required).
Server health, version, and build info. Start here when diagnosing anything. Returns {health, about, config}.
Inputs: no named parameters.
All mailing lists with id, name, type, opt-in mode, tags, and subscriber counts.
Inputs: no named parameters.
Update a mailing list. Only the fields you pass change; the rest are kept from the current list.
Inputs: id (required), name, tags, type, +2 more.
Create a subscriber. list_ids subscribes them to lists. preconfirm skips double opt-in confirmation for double opt-in lists.
Inputs: email (required), name, status, attribs, +2 more.
Permanently delete a subscriber by id, with their list subscriptions and campaign history.
Inputs: id (required).
One subscriber by id, including their list memberships.
Inputs: id (required).
Bulk add, remove, or unsubscribe subscribers from lists without replacing their other memberships. action: add | remove | unsubscribe.
Inputs: action (required), list_ids (required), subscriber_ids (required), status.
Search subscribers. Pass query as a Listmonk SQL expression on the subscribers table, e.g. subscribers.email LIKE '%@example.com' or subscribers.status = 'blocklisted'. Omit query to list all.
Inputs: page, query, list_id, per_page, +1 more.
Update a subscriber. Only the fields you pass change. Passing list_ids replaces their list memberships; use subscribers_lists_change to add or remove without replacing.
Inputs: id (required), name, email, status, +3 more.
Create a template. type is 'campaign' (for campaigns) or 'tx' (for transactional sends). body must contain {{ template "content" . }} for campaign templates.
Inputs: body (required), name (required), type (required), subject.
Permanently delete a template. Listmonk refuses to delete the default template or one in use by a campaign.
Inputs: id (required).
One template by id, including its HTML body.
Inputs: id (required).
All campaign and transactional templates with id, name, type, and default flag.
Inputs: no named parameters.
Update a template. Only the fields you pass change.
Inputs: id (required), body, name, subject.
Send one transactional email from a 'tx' template to a subscriber email. data fills template placeholders. Sends real mail.
Inputs: template_id (required), subscriber_email (required), data, subject, +2 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 32 tools
Most tools map cleanly to a resource+action, and the descriptions proactively disambiguate the risky pairs (subscriber_update vs subscribers_lists_change, campaign_update vs campaign_set_status). The only residual overlap is mild: several prefixed system tools (status, dashboard_counts, logs, settings_get) all return 'instance info', though their specific outputs are distinct enough.
The underlying pattern is verb_noun with a resource prefix, which is readable and mostly predictable. However prefixes flip between singular and plural (subscriber_delete vs subscribers_search, list_get vs lists_list, campaign_get vs campaigns_search), which is a genuine convention inconsistency.
32 tools is heavy, but the server genuinely spans seven resource areas (subscribers, lists, campaigns, templates, bounces, transactional sends, system diagnostics), so most tools earn their place. Still, it sits in the 25+ range where an agent has to scan a lot of surface.
CRUD coverage is solid for lists, subscribers, campaigns, and templates, with bounces and transactional sending appropriately read/delete-only and send-only. Minor gaps: no bulk subscriber import/export and no listing subscribers per-list outside SQL search expressions.
Send email, manage domains, templates, webhooks and broadcasts from your AI agent.
MailBeast.ai is a cold email outreach platform. This server lets AI assistants create and launch campaigns with multi-step A/B sequences, manage leads and sending mailboxes (health, warmup, limits), read and answer replies from a unified inbox, and pull campaign analytics. OAuth 2.1 sign-in with read-only or read-and-write access; an API key header is also supported. Website: https://mailbeast.ai
Email infrastructure for AI agents: send, read replies as threads, campaigns, per-key limits.
Email and SMS infrastructure, run by your agent: send, campaigns, contacts, domains, webhooks.
