listmonk-mcp-bridge 0.4.6

Production-ready MCP server for Listmonk newsletter and mailing list management

Listmonk MCP Bridge

MCP server for Listmonk newsletter operations.

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

• Tool list: https://mnbro.github.io/listmonk-mcp-bridge/tools/
• Docker: https://mnbro.github.io/listmonk-mcp-bridge/docker/
• Configuration: https://mnbro.github.io/listmonk-mcp-bridge/configuration/
• MCP clients: https://mnbro.github.io/listmonk-mcp-bridge/mcp-clients/
• API coverage: https://mnbro.github.io/listmonk-mcp-bridge/api-coverage/
• Safeguards: https://mnbro.github.io/listmonk-mcp-bridge/safeguards/

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.

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

LLM-friendly helper tools

This MCP remains a generic Listmonk domain MCP. It does not orchestrate external systems, call other MCP servers, or hardcode external workflows.

The helper tools are built on top of the existing Listmonk API wrappers. They give LLM agents safer primitives for subscriber profile sync, audience inspection, personalization validation, campaign risk checks, guarded sends, generic exports and audit logs.

Recommended helper tools for agents:

• upsert_subscriber_profiles
• get_subscriber_context
• audience_summary
• personalization_fields_report
• validate_message_personalization
• campaign_risk_check
• safe_send_campaign
• safe_schedule_campaign
• safe_send_transactional_email
• campaign_performance_summary
• export_engagement_events
• export_campaign_markdown
• export_campaign_postmortem_markdown
• export_subscriber_communication_summary

Example profile sync dry run:

{
  "profiles": [
    {
      "externalId": "abc-123",
      "source": "external-system",
      "email": "[e-mail]",
      "name": "Jane Doe",
      "attributes": {
        "birthday": "1990-05-10",
        "customer_type": "vip"
      },
      "tags": ["vip"],
      "listIds": [1, 2],
      "status": "enabled"
    }
  ],
  "dryRun": true
}

upsert_subscriber_profiles looks up existing subscribers by email before planning or applying changes. In the current implementation that lookup uses Listmonk's subscriber SQL query capability, so the MCP API key needs the subscribers:sql_query permission. Without it, dry runs and upserts can return a Listmonk permission error.

Example personalization and send checks:

{
  "email": "[e-mail]"
}

{
  "listIds": [1, 2],
  "filters": {}
}

{
  "subject": "Hello {{name}}",
  "body": "We have an update for {{customer_type}} subscribers.",
  "listIds": [1],
  "sampleSubscriberIds": [123, 456]
}

{
  "campaignId": 123,
  "requireTestSend": true,
  "maxAudienceSize": 5000
}

{
  "campaignId": 123,
  "confirmSend": true,
  "approval": {
    "required": true,
    "status": "approved",
    "approvalId": "approval-123"
  },
  "requireTestSend": true,
  "testRecipients": ["[e-mail]"]
}

{
  "templateId": 10,
  "recipientEmail": "[e-mail]",
  "subject": "A message for Jane",
  "data": {
    "name": "Jane",
    "customMessage": "Happy birthday"
  },
  "contentType": "html",
  "confirmSend": true,
  "idempotencyKey": "unique-event-key-123"
}

Example generic exports:

{
  "campaignId": 123,
  "fromDate": "2026-04-01",
  "toDate": "2026-04-30"
}

{
  "campaignId": 123,
  "eventTypes": ["email_viewed", "email_clicked"]
}

{
  "campaignId": 123,
  "includeBody": true,
  "includeStats": true
}

{
  "subscriberId": 123,
  "fromDate": "2026-01-01",
  "toDate": "2026-04-30"
}

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.