listmonk-mcp-ts
Provides tools for interacting with a Listmonk instance, enabling AI agents to manage subscribers, mailing lists, campaigns (including body editing via plain-text, regex and batch replace), templates, media, and to send transactional email.
Listmonk MCP Server

An MCP server for Listmonk, the self-hosted newsletter and mailing list manager. It lets AI agents (Claude Code, Claude Desktop, Cursor, Cline, VS Code and others) manage subscribers, mailing lists, campaigns, templates and media, and send transactional email through your Listmonk instance.
TypeScript port of rhnvrm/listmonk-mcp by Rohan Verma, extended with file-based templates, campaign body editing and hardened file access.
Written in TypeScript, runs on Bun.
Features
Subscribers: add, update, delete, change status, search with Listmonk SQL queries, look up by ID or email.
Mailing lists: create, update, delete, list, list members.
Campaigns: create, update, preview, send now, schedule. Edit the body with plain-text, regex and batch replace.
Templates: create, update, delete, read. Large HTML bodies (for example MJML exports) can be loaded straight from a file.
Transactional email: send a
txtemplate to one recipient with custom data.Media: upload, rename, delete, list.
Related MCP server: sendook-mcp
Requirements
Bun 1.1 or newer.
Listmonk with an API user. In the Listmonk admin, open Users, create a user of type API and copy its token. Give it a role with only the permissions the agent needs.
Quick start
One-click install (then replace the placeholder URL, user and token in the client's MCP settings):
Claude Code
claude mcp add --transport stdio --scope user \
--env LISTMONK_MCP_URL=https://listmonk.example.com \
--env LISTMONK_MCP_USERNAME=api_user \
--env LISTMONK_MCP_PASSWORD=your-api-token \
listmonk -- bunx listmonk-mcp-tsClaude Desktop, Cursor, Cline and other clients
Add the server to the client's MCP config (mcpServers section):
{
"mcpServers": {
"listmonk": {
"command": "bunx",
"args": ["listmonk-mcp-ts"],
"env": {
"LISTMONK_MCP_URL": "https://listmonk.example.com",
"LISTMONK_MCP_USERNAME": "api_user",
"LISTMONK_MCP_PASSWORD": "your-api-token",
"LISTMONK_MCP_FILES_DIR": "/path/to/email-templates"
}
}
}
}Where the config file lives for each client: Claude Desktop, Cursor and Windsurf, Cline, VS Code.
The server is started by the client when a session opens and stops with it. You do not need to keep it running.
Configuration
Variable | Required | Default | Description |
| yes | Listmonk base URL, | |
| yes | API user name | |
| yes | API user token | |
| no | Directory the file tools may read from. File tools are disabled when it is not set | |
| no |
| HTTP timeout, seconds |
| no |
| Retries on network errors. Only GET requests are retried |
| no |
| Server name reported to the client |
Variables can also come from a .env file in the working directory, or from a file passed with --config /path/to/.env.
CLI options: -c, --config <file> loads an env file, -v, --version prints the version.
Tools
Area | Tools |
Health |
|
Subscribers |
|
Mailing lists |
|
Campaigns |
|
Campaign body |
|
Templates |
|
Transactional |
|
Media |
|
Templates from a file
Passing a large HTML body inline through a tool call is slow and the model can change it while copying. create_template_from_file and update_template_from_file read the body from a file instead, so the stored template matches the file byte for byte. subject is required for tx templates.
The file path can be absolute or relative to LISTMONK_MCP_FILES_DIR.
Security
File access is limited to
LISTMONK_MCP_FILES_DIR.create_template_from_file,update_template_from_fileandupload_media_filerefuse any path outside it, symlinks included, and are disabled when it is not set. Subscriber names, campaign bodies and other data read from Listmonk may contain instructions written by strangers (prompt injection). Without this limit such text could make the agent read~/.sshor.envand email it out.Keep approval on for sending tools.
send_campaign,schedule_campaignandsend_transactional_emailsend real email. Do not auto-approve them in your client.Use a dedicated API user with a role limited to what the agent needs, not an admin account.
Keep the token out of shared files. If your MCP config is committed or synced, pass the token through the environment instead.
Development
git clone https://github.com/tecspda/listmonk-mcp-ts.git
cd listmonk-mcp-ts
bun install
cp .env.example .env # fill in your Listmonk details
bun run start # run the server
bun run dev # run with reload on change
bun run check # type check
bun test # testsTo run a local checkout from an MCP client, use "command": "bun", "args": ["run", "/path/to/listmonk-mcp-ts/src/index.ts"].
Need a Listmonk instance for testing? See Docker setup.
License
Available Tools
36 toolsadd_subscriberA
Create a new subscriber and optionally subscribe them to mailing lists. Fails if a subscriber with the same email already exists. Returns the new subscriber ID. To change an existing subscriber use update_subscriber.
Inputs: name (required), email (required), lists, status, +2 more.
batch_replace_in_campaign_bodyADestructive
Apply several literal search and replace pairs to a campaign's body in the given order, then save once. Later pairs see the result of earlier ones, and empty search texts are skipped. Nothing is saved if no pair matches.
Inputs: campaign_id (required), replacements (required).
change_subscriber_statusADestructiveIdempotent
Change only a subscriber's status to enabled, disabled or blocklisted. Blocklisted subscribers are excluded from all campaigns. Use remove_subscriber to delete the record instead.
Inputs: status (required), subscriber_id (required).
check_listmonk_healthARead-only
Check that the Listmonk server is reachable and responding, and return its health data. Makes a single request with no retries. Use it first when other tools fail with connection errors.
Inputs: no named parameters.
create_campaignA
Create a campaign in draft status; nothing is sent yet. body is the message content and template_id selects the layout template that wraps it. Returns the new campaign ID. Next, review it with get_campaign_preview, then start it with send_campaign or schedule_campaign.
Inputs: name (required), lists (required), subject (required), body, +4 more.
create_mailing_listA
Create a mailing list and return its ID, which other tools use to subscribe people and target campaigns. A list is public or private and uses single or double opt-in.
Inputs: name (required), tags, type, optin, +1 more.
create_templateA
Create a template and return its ID. Type 'campaign' is a layout that wraps campaign bodies; type 'tx' is a transactional email template that needs a subject and is sent with send_transactional_email. For large HTML bodies prefer create_template_from_file.
Inputs: body (required), name (required), type, subject, +1 more.
create_template_from_fileA
Create a template whose HTML body is read from a UTF-8 file inside LISTMONK_MCP_FILES_DIR, so large bodies such as MJML exports are stored byte for byte. Otherwise identical to create_template. Fails if LISTMONK_MCP_FILES_DIR is not set or the path is outside it.
Inputs: name (required), file_path (required), type, subject, +1 more.
delete_mailing_listADestructiveIdempotent
Permanently delete a mailing list and its subscriptions. The subscribers themselves are kept and only leave this list. This cannot be undone.
Inputs: list_id (required).
delete_media_fileADestructiveIdempotent
Permanently delete a media file. Campaigns or templates that still link to its URL will show a broken file. This cannot be undone.
Inputs: media_id (required).
delete_templateADestructiveIdempotent
Permanently delete a template by ID. This cannot be undone. Check get_templates first so you do not delete one that is still needed.
Inputs: template_id (required).
get_campaignARead-only
Get one campaign by ID: name, subject, status, type, template, target lists, send progress, view and click counts, and the full body (which can be large).
Inputs: campaign_id (required).
get_campaign_previewARead-only
Render a preview of the campaign as the HTML subscribers would see. Read-only: nothing is sent. Use it to check a campaign before send_campaign or schedule_campaign.
Inputs: campaign_id (required).
get_campaignsARead-only
List campaigns, one page at a time, with ID, name, status, sent/total progress and target list IDs. Optionally filter by status. Use get_campaign for one campaign's full details and body.
Inputs: page, status, per_page.
get_list_by_idARead-only
Get one mailing list by ID: name, type, opt-in mode, subscriber count, tags, description and timestamps.
Inputs: list_id (required).
get_list_subscribers_toolARead-only
List the subscribers of one mailing list, one page at a time, with name, email and status, plus the list's total subscriber count. Use get_mailing_lists to find list IDs.
Inputs: list_id (required), page, per_page.
get_mailing_listsARead-only
List mailing lists with ID, type, subscriber count and tags. Use it to find the list IDs required by add_subscriber, create_campaign and other tools.
Inputs: no named parameters.
get_media_listARead-only
List uploaded media files with ID, filename, title, size, creation date and public URL. The URL can be used in campaign and template HTML.
Inputs: no named parameters.
get_subscriber_by_emailARead-only
Look up one subscriber by exact email address and return the same details as get_subscriber_by_id. Returns a not-found error if no subscriber has that address.
Inputs: email (required).
get_subscriber_by_idARead-only
Get one subscriber by numeric ID: email, name, status, timestamps, list memberships and custom attributes. Returns an error if the ID does not exist. Use get_subscriber_by_email when you only know the address.
Inputs: subscriber_id (required).
get_templateARead-only
Get one template by ID: name, type (campaign or tx), default flag, subject (tx only), update time and the full HTML body, which can be large.
Inputs: template_id (required).
get_templatesARead-only
List all templates (campaign layouts and transactional) with ID, name, type and default flag. Use the IDs with create_campaign, send_transactional_email or update_template.
Inputs: no named parameters.
list_subscribersARead-only
List subscribers, newest first, one page at a time. Returns the total subscriber count and each subscriber's name, email, status and list names. Use query to filter with a SQL expression; use get_subscriber_by_email when you already know the address.
Inputs: page, query, per_page.
regex_replace_in_campaign_bodyADestructive
Replace all matches of a JavaScript regular expression in a campaign's body and save the campaign. Reports how many matches were replaced and changes nothing if there is no match. An invalid pattern returns an error. For plain text use replace_in_campaign_body.
Inputs: pattern (required), replace (required), campaign_id (required).
remove_subscriberADestructiveIdempotent
Permanently delete a subscriber and all their list subscriptions. This cannot be undone. To stop mailing someone but keep their record, use change_subscriber_status with 'blocklisted' instead.
Inputs: subscriber_id (required).
rename_mediaADestructiveIdempotent
Change a media file's display title in the media library. The filename and public URL stay the same, so existing links keep working.
Inputs: media_id (required), new_title (required).
replace_in_campaign_bodyADestructive
Replace every occurrence of a literal text in a campaign's body (case-sensitive, not a regex) and save the campaign. Reports how many replacements were made and changes nothing if the text is not found. For patterns use regex_replace_in_campaign_body; for several replacements in one save use batch_replace_in_campaign_body.
Inputs: search (required), replace (required), campaign_id (required).
schedule_campaignADestructiveIdempotent
Schedule a campaign to start sending automatically at a future date and time. Nothing is sent now. Use send_campaign to send immediately instead.
Inputs: send_at (required), campaign_id (required).
send_campaignADestructive
Start sending a campaign to its target lists right now by setting its status to running. This emails real subscribers and cannot be undone, so check get_campaign_preview first. It returns as soon as sending starts and delivery continues in the background; follow progress with get_campaign. To send later use schedule_campaign.
Inputs: campaign_id (required).
send_transactional_emailADestructive
Send one transactional email right away, using a 'tx' template, to a subscriber that already exists in Listmonk. The email cannot be recalled. data fills the template variables. Create tx templates with create_template (type 'tx').
Inputs: template_id (required), subscriber_email (required), data, content_type.
update_campaignADestructiveIdempotent
Update a campaign's name, subject, target lists, body or tags. Only the fields you provide are sent, and the target lists are kept if you omit lists. Use it before sending, because Listmonk may reject edits once a campaign is running. Does not send anything.
Inputs: campaign_id (required), body, name, tags, +2 more.
update_mailing_listADestructiveIdempotent
Update a mailing list's name, type, opt-in mode, tags or description. Only the fields you provide are sent. Existing subscribers are not removed.
Inputs: list_id (required), name, tags, type, +2 more.
update_subscriberADestructiveIdempotent
Update an existing subscriber's email, name, status, list memberships or attributes. Only the fields you provide are sent to Listmonk. When lists or attributes is provided it is sent as the full new value, not merged with the old one. To only change status use change_subscriber_status.
Inputs: subscriber_id (required), name, email, lists, +2 more.
update_templateADestructiveIdempotent
Update a template's name, body, default flag or subject. Only the fields you provide are sent, and a provided body replaces the old one completely. For large HTML bodies prefer update_template_from_file.
Inputs: template_id (required), body, name, subject, +1 more.
update_template_from_fileADestructiveIdempotent
Update an existing template, replacing its HTML body with the contents of a UTF-8 file inside LISTMONK_MCP_FILES_DIR. Otherwise identical to update_template. Fails if LISTMONK_MCP_FILES_DIR is not set or the path is outside it.
Inputs: file_path (required), template_id (required), name, subject, +1 more.
upload_media_fileA
Upload a file from LISTMONK_MCP_FILES_DIR to the Listmonk media library and return its ID and public URL for use in campaign bodies. Fails if LISTMONK_MCP_FILES_DIR is not set or the path is outside it. Image types (jpg, png, gif, webp, svg) get the right MIME type; other types upload as generic binary and Listmonk may reject them.
Inputs: file_path (required), title.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 36 tools
Most tools target clearly distinct resources and actions, with helpful cross-references in descriptions (e.g. get_subscriber_by_id vs get_subscriber_by_email, send_campaign vs schedule_campaign). The main overlaps are the three campaign-body replacement variants and the file-based template creation/update variants, but each is explicitly differentiated.
The set predominantly follows a verb_noun convention (add_subscriber, update_campaign, delete_template), with mostly snake_case names. Minor deviations exist: listing uses both 'get' (get_mailing_lists, get_media_list) and 'list' (list_subscribers), and get_list_subscribers_tool has an inconsistent '_tool' suffix.
At 36 tools, the surface is quite large for one MCP server and exceeds the typical well-scoped range. While the domain is broad (subscribers, lists, campaigns, templates, media), several tools are close variants, making the set heavier than necessary.
Core newsletter workflows are well covered: subscriber and list CRUD, campaign creation/preview/send/schedule, template CRUD with file-based variants, transactional email, and media management. A few lifecycle gaps remain, such as campaign deletion or duplication and broader subscriber import/bulk operations, but agents can work around these.
Maintenance
Related MCP Connectors
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/.
MCP server for Lemon Squeezy — stores, products, orders, subscriptions, license keys.
Email API + newsletters. 17 MCP tools. OAuth 2.1 PKCE or API key. EU-hosted (Hetzner + SES).
MCP server for Nylas — read email, calendars, events and contacts, and send email or create events.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn MCP server implementation that enables AI assistants to interact with Listmonk instances, providing programmatic access to newsletter and mailing list management functionality including subscriber, list, and campaign operations.237 PyPI45MIT
- AlicenseAqualityDmaintenanceMCP server for Sendook - an AI email communication platform. Enables AI agents to send and receive emails, manage inboxes, threads, and webhooks programmatically.16MIT
- FlicenseDqualityBmaintenanceEnables AI agents to manage Listmonk email campaigns, subscribers, lists, and analytics through typed MCP tools with production safety features.37322 PyPI2-
- AlicenseNot gradedqualityBmaintenanceMCP server for the big-mailer self-hosted email platform, exposing 93 tools to manage subscribers, consent, sequences, broadcasts, segments, and Stripe reconciliation via natural language.11MIT