Overview

The Listmonk MCP Server exposes Listmonk newsletter and mailing-list functionality via the Model Context Protocol (MCP). It acts as a bridge between LLMs / AI assistants and a Listmonk installation, mapping MCP tools and resources onto Listmonk’s REST API so models can manage subscribers, lists, campaigns and templates programmatically.

This is useful when you want to automate newsletter workflows, let agents generate or modify campaigns, or integrate Listmonk with other systems (CRMs, data pipelines) using LLM-driven logic. The server is asynchronous, type-safe (Pydantic), and intended to be run alongside a Listmonk instance (local or hosted).

Features

Complete coverage of core Listmonk operations (subscribers, lists, campaigns, templates, analytics)
Exposes MCP-compatible tools and resources for AI model access
Asynchronous implementation with async/await
Pydantic models for input/output validation
Environment-driven configuration for easy deployment
CLI entry point and PyPI package for simple installation
Development tooling and CI-friendly checks included

Installation / Configuration

Recommended options: run directly with uvx or install from PyPI. For development you can clone the repo.

Install from PyPI:

pip install listmonk-mcp

Run directly with uvx (installs if needed):

# Run once
uvx listmonk-mcp --help

# Or install globally and run
uvx install listmonk-mcp
listmonk-mcp --help

Development install:

git clone https://github.com/rhnvrm/listmonk-mcp.git
cd listmonk-mcp
uv sync --extra dev
uv run python -m listmonk_mcp.server

Required environment variables:

export LISTMONK_MCP_URL="http://localhost:9000"
export LISTMONK_MCP_USERNAME="api-user"
export LISTMONK_MCP_PASSWORD="your-generated-api-token"

Environment variables explained:

Variable	Description
LISTMONK_MCP_URL	Base URL of your Listmonk instance (e.g. http://localhost:9000)
LISTMONK_MCP_USERNAME	API username created in Listmonk
LISTMONK_MCP_PASSWORD	API token generated for the user (used as password)

Note: Listmonk expects the Authorization header in the format: Authorization: token username:api_token

Quick sanity check for Listmonk API access:

curl -H "Authorization: token api-user:your-generated-api-token" \
  http://localhost:9000/api/health

Start the MCP server:

# with Python module entrypoint (development)
python -m listmonk_mcp.server

# or via installed CLI
listmonk-mcp

Common issues:

“connection refused” — verify LISTMONK_MCP_URL and that Listmonk is running
403 / “invalid session” — check the API token and username

Available Resources and Tools

The server exposes MCP resources that map to Listmonk entities and operations. High-level categories:

Subscribers: add, update, remove, fetch subscribers; bulk import support
Lists: create, update, get lists, manage list settings
Campaigns: create campaigns, schedule/send, preview, fetch campaign stats
Templates & Content: manage templates and message content
Analytics: access campaign reports, open/click metrics, and aggregate stats

These tools are designed to be used by LLMs following the MCP pattern (tool calls with structured input, typed outputs). The repo implements a comprehensive set of tools (covering the above categories) and resource models validated with Pydantic.

Use Cases

Automated subscriber onboarding: ingest leads from a CRM, normalize fields, and call the MCP tools to add or update subscribers in specific mailing lists.
LLM-driven campaign creation: prompt an assistant to generate newsletter content and metadata, then have the MCP tools create a campaign, preview it, and schedule a send.
Reporting and monitoring: run periodic prompts that request campaign metrics; the MCP server returns structured analytics for dashboards or alerts.
A/B testing orchestration: programmatically create variant campaigns, schedule sends, and fetch performance metrics to decide winners.
Integration pipelines: tie Listmonk into ETL jobs or serverless functions that need to programmatically manage lists and subscribers.

Example: Add a subscriber (conceptual flow)

LLM decides to add a subscriber and calls the “add_subscriber” tool with a JSON payload.
MCP server validates input with Pydantic and forwards the request to Listmonk API.
On success, the tool returns the created subscriber object and any Listmonk metadata.

Development and CI

Development helpers:

# Install dev deps
uv sync --extra dev

# Lint and type-check (same as CI)
uv run ruff check src/
uv run mypy src/

Versioning and release are handled via updating pyproject.toml, tagging Git commits, and letting GitHub Actions build/publish the package.

Where to find the project

Source code, issues, and contributions: https://github.com/rhnvrm/listmonk-mcp

If you plan to integrate this server with production Listmonk instances, test locally first (Docker compose for Listmonk is a quick way to get started) and verify API tokens and network access before wiring it into automation workflows.

Listmonk MCP Server for Mailing List Management