Listmonk MCP

io.github.tecspdaPublished by GitHub account tecspdav0.1.3Updated Oct 30, 2026

Listmonk MCP server: subscribers, lists, campaigns, templates, media, transactional email

VerifiedSTDIODesktop onlyCommunication & CollaborationBusiness & Commerce

Overview

AI-generated overview

MCP server for a self-hosted Listmonk instance, letting an assistant manage subscribers, lists, campaigns, templates and media, and send email.

What you can do
  • Check Listmonk health and connection status
  • Add, update, remove, search and look up subscribers, and change their status
  • Create, update, delete and inspect mailing lists and their members
  • Create, update, preview, send now or schedule campaigns, and edit campaign bodies with plain, regex or batch replacement
  • Create, update, read and delete templates, including loading large HTML bodies from a file
  • Send transactional email from a tx template and upload, rename, list or delete media
When to use it
Useful when you run your own Listmonk newsletter server and want an assistant to handle routine list administration, draft or edit campaigns, manage templates and media, or send one-off transactional mail without clicking through the admin UI.
Requirements
Runs locally as a stdio process started by the MCP client; needs Bun 1.1 or newer (launched with bunx). Requires a reachable Listmonk base URL and an API user, supplied through LISTMONK_MCP_URL, LISTMONK_MCP_USERNAME and LISTMONK_MCP_PASSWORD. Optional LISTMONK_MCP_FILES_DIR enables the file-based template and media tools; timeout, retry and server-name variables are optional.
Before you install
The API token in LISTMONK_MCP_PASSWORD grants access to your mailing list data; use a dedicated API user with a limited role rather than an admin account, and keep the token out of shared or committed config files. send_campaign, schedule_campaign and send_transactional_email send real email, so keep approval on for them. Subscriber names and campaign bodies read from Listmonk may contain prompt injection; file tools are restricted to LISTMONK_MCP_FILES_DIR and disabled when it is unset.

Installation

In SourceWeft

  1. Open Listmonk MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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.

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

bash
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):

json
{  "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

VariableRequiredDefaultDescription
LISTMONK_MCP_URLyesListmonk base URL, http:// or https://
LISTMONK_MCP_USERNAMEyesAPI user name
LISTMONK_MCP_PASSWORDyesAPI user token
LISTMONK_MCP_FILES_DIRnoDirectory the file tools may read from. File tools are disabled when it is not set
LISTMONK_MCP_TIMEOUTno30HTTP timeout, seconds
LISTMONK_MCP_MAX_RETRIESno3Retries on network errors. Only GET requests are retried
LISTMONK_MCP_SERVER_NAMEnoListmonk MCP ServerServer 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

AreaTools
Healthcheck_listmonk_health
Subscribersadd_subscriber, update_subscriber, remove_subscriber, change_subscriber_status, list_subscribers, get_subscriber_by_id, get_subscriber_by_email
Mailing listsget_mailing_lists, get_list_by_id, get_list_subscribers_tool, create_mailing_list, update_mailing_list, delete_mailing_list
Campaignsget_campaigns, get_campaign, get_campaign_preview, create_campaign, update_campaign, send_campaign, schedule_campaign
Campaign bodyreplace_in_campaign_body, regex_replace_in_campaign_body, batch_replace_in_campaign_body
Templatesget_templates, get_template, create_template, update_template, create_template_from_file, update_template_from_file, delete_template
Transactionalsend_transactional_email
Mediaget_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

bash
git clone https://github.com/tecspda/listmonk-mcp-ts.gitcd listmonk-mcp-tsbun installcp .env.example .env   # fill in your Listmonk detailsbun run start          # run the serverbun run dev            # run with reload on changebun run check          # type checkbun 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

Source: README.md at commit 756dcf6

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the server did not start.

Version history

2
  1. v0.1.3LatestOct 29, 2026
  2. v0.1.1Oct 21, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts