Skip to main content
Glama
listmonk-mcp-ts

listmonk-mcp-ts

Listmonk MCP Server

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 tx template 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):

Install in Cursor Install in VS Code

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-ts

Claude 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

LISTMONK_MCP_URL

yes

Listmonk base URL, http:// or https://

LISTMONK_MCP_USERNAME

yes

API user name

LISTMONK_MCP_PASSWORD

yes

API user token

LISTMONK_MCP_FILES_DIR

no

Directory the file tools may read from. File tools are disabled when it is not set

LISTMONK_MCP_TIMEOUT

no

30

HTTP timeout, seconds

LISTMONK_MCP_MAX_RETRIES

no

3

Retries on network errors. Only GET requests are retried

LISTMONK_MCP_SERVER_NAME

no

Listmonk MCP Server

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

check_listmonk_health

Subscribers

add_subscriber, update_subscriber, remove_subscriber, change_subscriber_status, list_subscribers, get_subscriber_by_id, get_subscriber_by_email

Mailing lists

get_mailing_lists, get_list_by_id, get_list_subscribers_tool, create_mailing_list, update_mailing_list, delete_mailing_list

Campaigns

get_campaigns, get_campaign, get_campaign_preview, create_campaign, update_campaign, send_campaign, schedule_campaign

Campaign body

replace_in_campaign_body, regex_replace_in_campaign_body, batch_replace_in_campaign_body

Templates

get_templates, get_template, create_template, update_template, create_template_from_file, update_template_from_file, delete_template

Transactional

send_transactional_email

Media

get_media_list, upload_media_file, rename_media, delete_media_file

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_file and upload_media_file refuse 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 ~/.ssh or .env and email it out.

  • Keep approval on for sending tools. send_campaign, schedule_campaign and send_transactional_email send 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               # tests

To 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

MIT

Available Tools

36 tools
add_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_bodyA
Destructive

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_statusA
DestructiveIdempotent

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_healthA
Read-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_listA
DestructiveIdempotent

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_fileA
DestructiveIdempotent

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_templateA
DestructiveIdempotent

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_campaignA
Read-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_previewA
Read-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_campaignsA
Read-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_idA
Read-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_toolA
Read-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_listsA
Read-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_listA
Read-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_emailA
Read-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_idA
Read-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_templateA
Read-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_templatesA
Read-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_subscribersA
Read-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_bodyA
Destructive

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_subscriberA
DestructiveIdempotent

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_mediaA
DestructiveIdempotent

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_bodyA
Destructive

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_campaignA
DestructiveIdempotent

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_campaignA
Destructive

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_emailA
Destructive

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_campaignA
DestructiveIdempotent

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_listA
DestructiveIdempotent

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_subscriberA
DestructiveIdempotent

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_templateA
DestructiveIdempotent

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_fileA
DestructiveIdempotent

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

    A3.8/5.0

    Scored across 36 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      An 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 PyPI
      45
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for Sendook - an AI email communication platform. Enables AI agents to send and receive emails, manage inboxes, threads, and webhooks programmatically.
      16
      MIT
    • F
      license
      D
      quality
      B
      maintenance
      Enables AI agents to manage Listmonk email campaigns, subscribers, lists, and analytics through typed MCP tools with production safety features.
      37
      322 PyPI
      2
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP 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.
      11
      MIT