Skip to main content
Glama
listmonk-mcp-bridge

listmonk-mcp-bridge

by mnbro

Listmonk MCP Bridge

PyPI version Python versions License CI Docs Container Ruff mypy GitHub release Downloads

Connect Listmonk to AI agents so they can safely manage email lists, subscribers, campaigns, test sends, transactional emails, and performance reports.

Documentation: https://mnbro.github.io/listmonk-mcp-bridge/

What it does

listmonk-mcp-bridge lets MCP clients work with the Listmonk API through typed tools for subscribers, lists, campaigns, templates, media, analytics, imports, bounces and transactional messages.

Each bridge release is linked to a content-addressed Listmonk API contract in the compatibility matrix.

It includes runtime confirmations for destructive actions, real email sends and sensitive reads.

Related MCP server: Mailjet MCP Server

This MCP remains a generic Listmonk domain MCP. It does not orchestrate external systems, call other MCP servers, or hardcode external workflows. For full tool behavior and schemas, use the tool documentation and safeguards documentation.

Recommended for autonomous LLM/orchestrator use:

  • check_listmonk_health

  • get_mailing_lists

  • get_list_subscribers_tool

  • get_subscriber_context

  • audience_summary

  • personalization_fields_report

  • validate_message_personalization

  • campaign_risk_check

  • safe_test_campaign

  • safe_send_campaign

  • safe_schedule_campaign

  • safe_send_transactional_email

  • campaign_performance_summary

  • export_campaign_markdown

  • export_campaign_postmortem_markdown

  • export_engagement_events

  • export_subscriber_communication_summary

  • upsert_subscriber_profiles with dryRun=true before any non-dry-run execution

These tools are LLM-friendly because they return compact summaries, warnings and blockers; use guardrails for confirmations, risk checks, approvals and idempotency where relevant; avoid accidental sends; and are suitable building blocks for external business orchestrators.

Supervised / low-level only:

  • send_campaign

  • test_campaign

  • schedule_campaign

  • send_transactional_email

  • add_subscriber

  • update_subscriber

  • change_subscriber_status

  • manage_subscriber_lists

  • manage_subscriber_lists_by_query

  • delete_subscribers_by_query

  • blocklist_subscriber

  • blocklist_subscribers

  • blocklist_subscribers_by_query

  • remove_subscriber

  • remove_subscribers

  • create_campaign

  • update_campaign

  • update_campaign_status

  • archive_campaign

  • replace_in_campaign_body

  • regex_replace_in_campaign_body

  • batch_replace_in_campaign_body

  • create_template

  • update_template

  • delete_template

  • set_default_template

  • create_mailing_list

  • update_mailing_list

  • delete_mailing_list

  • delete_mailing_lists

  • import_subscribers

  • upload_media_file

  • delete_media_file

  • update_settings

  • reload_app

Some low-level tools have confirmation guards, but they are still closer to the raw Listmonk API. Prefer safe_* wrappers for LLM workflows. For content changes, preview and risk-check before mutating operations.

Campaign flow: check_listmonk_health -> audience_summary -> personalization_fields_report -> validate_message_personalization -> campaign_risk_check -> get_campaign_html_preview or export_campaign_markdown -> safe_test_campaign -> external approval if required -> safe_schedule_campaign or safe_send_campaign -> campaign_performance_summary -> export_campaign_postmortem_markdown.

Do not use send_campaign directly in an orchestrator. Do not use schedule_campaign directly unless there is an explicit low-level reason. Prefer safe_test_campaign before safe_send_campaign; when safe_send_campaign uses requireTestSend=true, provide testRecipients.

Transactional email flow: get_subscriber_context -> validate_message_personalization if subject/body are generated -> safe_send_transactional_email with confirmSend=false for a safety check -> safe_send_transactional_email with confirmSend=true only after an explicit decision. Use an idempotencyKey for recurring events, for example birthday-email:{subscriberId}:{year}.

Transactional data accepts object | null and may contain nested JSON. Some connector renderers show only example fields such as name and customMessage, but the schema keeps additionalProperties=true, so arbitrary template variables are allowed.

Subscriber sync flow: get_subscriber_context by email -> upsert_subscriber_profiles with dryRun=true -> inspect plannedCreated, plannedUpdated and errors -> run upsert_subscriber_profiles with dryRun=false only after external confirmation.

upsert_subscriber_profiles looks up subscribers by email. It needs the relevant Listmonk subscriber permissions, including subscribers:sql_query if SQL lookup is used. Email literals are quoted safely, including apostrophes. In production, use dryRun=true before any write.

Production safety model

  • Sensitive read tools require confirm_read.

  • Send tools require confirm_send.

  • Destructive tools require confirm.

  • Scheduling tools require confirm_send or confirmSchedule.

  • safe_* wrappers are preferred for LLM agents.

  • Approval metadata can block send/schedule even when confirmation is true.

  • idempotencyKey prevents duplicate transactional email sends.

  • Safe confirmed operations return an auditId.

License

This project is licensed under the PolyForm Internal Use License 1.0.0.

You may use and modify it for your own internal business operations, including commercial internal use. You may not redistribute it, resell it, sublicense it, or offer it as a productized service to third parties.

Install

Run directly with uvx:

uvx listmonk-mcp-bridge

Or install with pip:

pip install listmonk-mcp-bridge
listmonk-mcp-bridge

Configure

Required environment variables:

export LISTMONK_MCP_URL=https://listmonk.example.com
export LISTMONK_MCP_USERNAME=api-user
export LISTMONK_MCP_PASSWORD=your-api-token

Use a dedicated Listmonk API user and token. Do not use the default admin account in production.

MCP client config

{
  "mcpServers": {
    "listmonk-mcp-bridge": {
      "command": "uvx",
      "args": ["listmonk-mcp-bridge"],
      "env": {
        "LISTMONK_MCP_URL": "https://listmonk.example.com",
        "LISTMONK_MCP_USERNAME": "api-user",
        "LISTMONK_MCP_PASSWORD": "your-api-token"
      }
    }
  }
}

Docker

The Debian slim based container image is published to GitHub Container Registry:

docker run --rm -i \
  --env LISTMONK_MCP_URL=https://listmonk.example.com \
  --env LISTMONK_MCP_USERNAME \
  --env LISTMONK_MCP_PASSWORD \
  ghcr.io/mnbro/listmonk-mcp-bridge:latest

See the Docker documentation for MCP client configuration.

Development

uv sync --all-extras
uv run ruff check .
uv run pytest
uv run python -m mypy src tests
uv run mkdocs build --strict

Full setup, tool behavior, API coverage, client-specific configuration and security notes are in the documentation site.

Available Tools

37 tools
audience_catalogD
Read-onlyIdempotent

Inputs: limit. Returns: object

audience_summaryD
Read-onlyIdempotent

Inputs: listIds (required), filters. Returns: object

bounce_health_summaryD
Read-onlyIdempotent

Inputs: limit. Returns: object

campaign_catalogD
Read-onlyIdempotent

Inputs: limit, status. Returns: object

campaign_performance_summaryD
Read-onlyIdempotent

Inputs: campaignId (required), toDate, fromDate. Returns: object

campaign_preview_packD
Read-onlyIdempotent

Inputs: campaignId (required). Returns: object

campaign_risk_checkD
Read-onlyIdempotent

Inputs: campaignId (required), maxAudienceSize, requireTestSend. Returns: object

check_listmonk_healthD
Read-onlyIdempotent

Inputs: no named parameters. Returns: object

export_campaign_markdownD
Read-onlyIdempotent

Inputs: campaignId (required), includeBody, includeStats. Returns: object

export_campaign_postmortem_markdownD
Read-onlyIdempotent

Inputs: campaignId (required), toDate, fromDate. Returns: object

export_engagement_eventsD
Read-onlyIdempotent

Inputs: campaignId (required), toDate, fromDate, eventTypes. Returns: object

export_subscriber_communication_summaryD
Read-onlyIdempotent

Inputs: email, toDate, fromDate, subscriberId. Returns: object

get_list_subscribers_toolD
Read-onlyIdempotent

Inputs: list_id (required), page, per_page. Returns: object

get_mailing_listsD
Read-onlyIdempotent

Inputs: page, order, query, order_by, +1 more. Returns: object

get_subscriber_contextD
Read-onlyIdempotent

Inputs: email, subscriberId. Returns: object

import_status_summaryD
Read-onlyIdempotent

Inputs: no named parameters. Returns: object

listmonk_capability_reportD
Read-onlyIdempotent

Inputs: includePermissionProbe. Returns: object

listmonk_diagnosticsD
Read-onlyIdempotent

Inputs: no named parameters. Returns: object

media_library_summaryD
Read-onlyIdempotent

Inputs: limit. Returns: object

personalization_fields_reportD
Read-onlyIdempotent

Inputs: listIds (required), sampleSize. Returns: object

prepare_subscriber_importD
Read-onlyIdempotent

Inputs: filePreview (required). Returns: object

safe_add_subscriberD

Inputs: email (required), name, dryRun, status, +3 more. Returns: object

safe_assign_subscribers_to_listsD

Inputs: listIds (required), subscriberIds (required), dryRun, confirmApply. Returns: object

safe_bulk_add_subscribersD

Inputs: subscribers (required), dryRun, listIds, confirmApply. Returns: object

safe_create_campaign_draftD

Inputs: body (required), name (required), listIds (required), subject (required), +4 more. Returns: object

safe_import_subscribersD

Inputs: params (required), filePath (required), dryRun, confirmImport. Returns: object

safe_schedule_campaignD

Inputs: sendAt (required), campaignId (required), approval, confirmSchedule. Returns: object

safe_send_campaignD

Inputs: campaignId (required), approval, confirmSend, testRecipients, +1 more. Returns: object

safe_send_subscriber_optinD

Inputs: subscriberId (required), confirmSend. Returns: object

safe_send_transactional_emailD

Inputs: templateId (required), data, subject, confirmSend, +4 more. Returns: object

safe_test_campaignD

Inputs: campaignId (required), testRecipients (required), confirmSend. Returns: object

safe_update_campaign_contentD

Inputs: campaignId (required), body, dryRun, subject, +2 more. Returns: object

safe_upload_campaign_assetD

Inputs: filePath (required), title, dryRun, confirmUpload. Returns: object

template_catalogD
Read-onlyIdempotent

Inputs: limit. Returns: object

upsert_subscriber_profilesD

Inputs: profiles (required), dryRun. Returns: object

validate_message_personalizationD
Read-onlyIdempotent

Inputs: body (required), listIds (required), subject (required), sampleSubscriberIds. Returns: object

validate_subscriber_importD
Read-onlyIdempotent

Inputs: rows (required), requiredListIds. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    D1.5/5.0

    Scored across 37 tools

    Disambiguation2/5

    Many tools have overlapping purposes, especially around subscriber import (e.g., safe_add_subscriber, safe_bulk_add_subscribers, validate_subscriber_import, prepare_subscriber_import, safe_import_subscribers, import_status_summary) and campaigns (e.g., safe_create_campaign_draft, safe_update_campaign_content, safe_send_campaign, safe_schedule_campaign, safe_test_campaign, campaign_performance_summary). The boundaries between these tools are unclear, making it difficult for an agent to distinguish when to use which.

    Naming Consistency3/5

    Tool names are all in snake_case and many use a verb_prefix pattern, but the prefixes are inconsistent. For example, some use 'safe_', others 'get_', 'export_', 'validate_', etc. There is no uniform convention for indicating the action or resource, and some names like 'audience_catalog' or 'campaign_catalog' are vague.

    Tool Count2/5

    With 37 tools, the server feels bloated. The number is high for the likely domain scope (email marketing via Listmonk). Many tools could be merged or removed, such as the several subscriber import-related tools or the multiple campaign export tools.

    Completeness3/5

    The tool set covers a wide range of operations: health, diagnostics, subscribers (add, import, assign, opt-in), campaigns (create, update, send, schedule, test, preview, performance), templates, and exports. However, there are notable gaps: no tools for deleting campaigns, subscribers, or lists; no update for individual subscriber profile beyond upsert; no template creation or update. This leaves dead ends in common workflows.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    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
      Not graded
      quality
      C
      maintenance
      Enables AI agents to interact with Mailjet's contact, campaign, segmentation, statistics, and workflow APIs for managing email marketing operations through natural language.
      316 npm
      14
      Apache 2.0
    • 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 AI agents to manage mailing lists and contacts, read campaign reports with per-link clicks, and trigger automations. Supports lookups and updates by email address, tag and status management, and destructive operations with client confirmation.
      13
      MIT