Skip to main content
Glama
listmonk-mcp

listmonk-mcp

by monk24215

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 server

Configuration

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 tools
bounce_deleteDelete bounce recordA
Destructive

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 bounceC
Read-onlyIdempotent

One bounce record by id.

Inputs: id (required).

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

Permanently delete a campaign and its view and click statistics. Listmonk rejects deletion of running campaigns.

Inputs: id (required).

campaign_getGet campaignA
Read-onlyIdempotent

One campaign by id, including body, lists, and send statistics.

Inputs: id (required).

campaign_set_statusChange campaign statusA
Destructive

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).

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

Permanently delete a mailing list by id. Subscriptions to it are removed; subscriber records are kept.

Inputs: id (required).

list_getGet mailing listC
Read-onlyIdempotent

One mailing list by id.

Inputs: id (required).

listmonk_dashboard_countsDashboard countsA
Read-onlyIdempotent

Totals across the instance: subscribers by status, lists, campaigns, and messages.

Inputs: no named parameters.

listmonk_logsServer logsB
Read-onlyIdempotent

Recent Listmonk application log lines (ring buffer, not persisted).

Inputs: no named parameters.

listmonk_settings_getGet settingsA
Read-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 statusA
Read-onlyIdempotent

Server health, version, and build info. Start here when diagnosing anything. Returns {health, about, config}.

Inputs: no named parameters.

lists_listList mailing listsB
Read-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 subscriberA
Destructive

Permanently delete a subscriber by id, with their list subscriptions and campaign history.

Inputs: id (required).

subscriber_getGet subscriberB
Read-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.

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

Permanently delete a template. Listmonk refuses to delete the default template or one in use by a campaign.

Inputs: id (required).

template_getGet templateB
Read-onlyIdempotent

One template by id, including its HTML body.

Inputs: id (required).

templates_listList templatesA
Read-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

    B3.3/5.0

    Scored across 32 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • 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
      B
      quality
      B
      maintenance
      Enables 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.
      72
      121 npm
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      26
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT