listmonk-mcp
Provides tools for interacting with a self-hosted Listmonk instance, enabling management of lists, subscribers, campaigns, templates, and bounces, plus sending transactional emails and checking system status, dashboard counts, logs, settings, and SMTP configuration.
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 show me my subscriber lists and how many subscribers each has"
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.
listmonk-mcp
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).
Requirements
Node.js 18+
Listmonk v6.x with an API user (Admin -> Users -> API user)
Related MCP server: @kieksme/listmonk-mcp
Setup
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 serverConfiguration
Variable | 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 |
Tools (current)
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.
Security
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.
License
MIT
Available Tools
32 toolsbounce_deleteDelete bounce recordADestructive
Delete a bounce record by id. Does not change the subscriber's status; use subscriber_update to re-enable a subscriber.
Inputs: id (required).
bounce_getGet bounceCRead-onlyIdempotent
One bounce record by id.
Inputs: id (required).
bounces_searchSearch bouncesBRead-onlyIdempotent
Recorded bounces, newest first. Filter by bounce type (soft, hard, complaint) and campaign.
Inputs: page, type, per_page, campaign_id.
campaign_createCreate campaign draftA
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.
campaign_deleteDelete campaignADestructive
Permanently delete a campaign and its view and click statistics. Listmonk rejects deletion of running campaigns.
Inputs: id (required).
campaign_getGet campaignARead-onlyIdempotent
One campaign by id, including body, lists, and send statistics.
Inputs: id (required).
campaign_set_statusChange campaign statusADestructive
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).
campaigns_searchSearch campaignsCRead-onlyIdempotent
List campaigns. Filter by status (draft, scheduled, running, paused, cancelled, finished) and optional query text.
Inputs: page, query, status, per_page.
campaign_test_sendSend campaign testA
Send a test copy of a campaign to up to 10 email addresses. Sends real mail to those addresses.
Inputs: id (required), emails (required).
campaign_updateUpdate campaignA
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.
list_createCreate mailing listC
Create a mailing list. type is 'public' or 'private'; optin is 'single' or 'double'.
Inputs: name (required), tags, type, optin, +1 more.
list_deleteDelete mailing listADestructive
Permanently delete a mailing list by id. Subscriptions to it are removed; subscriber records are kept.
Inputs: id (required).
list_getGet mailing listCRead-onlyIdempotent
One mailing list by id.
Inputs: id (required).
listmonk_dashboard_countsDashboard countsARead-onlyIdempotent
Totals across the instance: subscribers by status, lists, campaigns, and messages.
Inputs: no named parameters.
listmonk_logsServer logsBRead-onlyIdempotent
Recent Listmonk application log lines (ring buffer, not persisted).
Inputs: no named parameters.
listmonk_settings_getGet settingsARead-onlyIdempotent
Instance settings. Passwords, keys, and tokens are replaced with [redacted] before being returned.
Inputs: no named parameters.
listmonk_smtp_testTest SMTP connectionA
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).
listmonk_statusListmonk statusARead-onlyIdempotent
Server health, version, and build info. Start here when diagnosing anything. Returns {health, about, config}.
Inputs: no named parameters.
lists_listList mailing listsBRead-onlyIdempotent
All mailing lists with id, name, type, opt-in mode, tags, and subscriber counts.
Inputs: no named parameters.
list_updateUpdate mailing listB
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.
subscriber_createCreate subscriberB
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.
subscriber_deleteDelete subscriberADestructive
Permanently delete a subscriber by id, with their list subscriptions and campaign history.
Inputs: id (required).
subscriber_getGet subscriberBRead-onlyIdempotent
One subscriber by id, including their list memberships.
Inputs: id (required).
subscribers_lists_changeChange subscriber list membershipB
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.
subscribers_searchSearch subscribersBRead-onlyIdempotent
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.
subscriber_updateUpdate subscriberA
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.
template_createCreate templateB
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.
template_deleteDelete templateADestructive
Permanently delete a template. Listmonk refuses to delete the default template or one in use by a campaign.
Inputs: id (required).
template_getGet templateBRead-onlyIdempotent
One template by id, including its HTML body.
Inputs: id (required).
templates_listList templatesARead-onlyIdempotent
All campaign and transactional templates with id, name, type, and default flag.
Inputs: no named parameters.
template_updateUpdate templateB
Update a template. Only the fields you pass change.
Inputs: id (required), body, name, subject.
tx_sendSend transactional emailB
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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
Tools are organized around distinct resources and actions, so most selections are clear. A few areas could be confused, such as subscriber_update versus subscribers_lists_change and the several email-sending tools, but their descriptions make the intended use distinguishable.
Names are consistently snake_case and mostly follow a resource_action pattern, with plural collection names like subscribers_search and singular record names like subscriber_get. Minor deviations exist, including the listmonk_ prefix for system tools and mixed collection verbs such as list versus search.
32 tools is heavy for an MCP surface, even though Listmonk is a broad domain with multiple CRUD-managed resources. Most tools map to real operations, but the count is borderline and could overwhelm agents selecting among many similar resource actions.
Core lifecycle coverage is strong across lists, subscribers, campaigns, templates, bounces, and system diagnostics. Minor gaps remain, such as no settings update, subscriber import/export, campaign preview beyond campaign_get, and media management.
Related MCP Connectors
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
Control newsletters, contacts and automations of Inviomail (German newsletter & email automation tool) from Claude, ChatGPT or your own agents. Hosted in Germany. Remote MCP server with 90+ tools for contacts, lists, tags, newsletters, automation flows and reports. OAuth or Bearer MCP key. Docs: https://admin.inviomail.de/api/docs/mcp
Read Buttondown subscribers, emails, analytics and automations; add subscribers; write email drafts.
Official remote MCP server of MailSenpai, the EU-hosted email marketing platform. Connect Claude, ChatGPT, Cursor or another MCP client with OAuth 2.1 and PKCE. 74 tools manage lists, subscribers, segments, templates, draft campaigns and stats, and check email DNS, blacklists and spam. Sends and deletions require explicit confirmation; every call is logged. The same team also offers SMTP Senpai, an SMTP relay and email API for transactional sending: https://en.mailsenpai.com/smtp-senpai/.
Related MCP Servers
- FlicenseDqualityBmaintenanceEnables AI agents to manage Listmonk email campaigns, subscribers, lists, and analytics through typed MCP tools with production safety features.37322 PyPI2-
- AlicenseBqualityBmaintenanceEnables MCP-compatible LLM clients to manage a Listmonk instance end-to-end through its full REST API, covering subscribers, campaigns, lists, templates, media, bounces, imports, settings, transactional messages, and admin functions, with selective tool loading for a leaner context.72121 npm1MIT
- AlicenseBqualityCmaintenanceEnables Claude and other MCP clients to work with SendPulse WhatsApp chatbots, reading bots, contacts, chats, tags and variables, and sending messages, approved templates, flows and campaigns. Supports multiple SendPulse accounts and an optional read-only mode that exposes only the 10 read tools.26MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude to manage a self-hosted PocketBase instance: querying and editing records, inspecting and changing collection schemas, handling files, users and backups, and auditing API rules for exposure risks. Writes are gated by a read-only mode plus a two-step confirmation that returns a preview diff and single-use token, so nothing changes until the identical call is approved.18 npmMIT