listmonk-api¶

A Python API client, MCP Server, and A2A agent for Listmonk — the self-hosted newsletter and mailing-list manager — built on the agent-utilities ecosystem.

Official documentation

This site is the canonical reference for listmonk-api, maintained alongside every release.

Overview¶

listmonk-api wraps Listmonk's REST API with a typed, modular Python client and a deterministic MCP tool surface, and ships a Pydantic-AI agent server for conversational automation. It provides:

ListmonkAPI — a delegated-subclassing client that aggregates dedicated sub-API managers for subscribers, lists, campaigns, media, templates, imports, and transactional messaging.
Action-routed MCP tools — togglable tool modules that group related operations to minimize LLM context overhead while keeping permissions granular.
An integrated A2A agent — a Pydantic-AI graph agent (console script listmonk-agent) with an optional web interface, wired to the MCP server.

The connector remains inactive when credentials are absent, so it is safe to install ahead of provisioning a Listmonk instance.

Explore the documentation¶

Installation — pip, source, extras, and the prebuilt Docker image.
Deployment — run the MCP and agent servers, Docker Compose, Caddy + Technitium.
Usage — the MCP tools, the ListmonkAPI client, and the agent CLI.
Backing Platform — deploy Listmonk with Docker.
Overview — API structure, tool reference, and quick start.
Concepts — the CONCEPT:LM-* registry.

Quick start¶

pip install "listmonk-api[all]"
listmonk-mcp                     # stdio MCP server (default transport)

Connect it to a Listmonk instance:

export LISTMONK_URL=https://listmonk.yourdomain.com
export LISTMONK_TOKEN=your-bearer-token
listmonk-mcp --transport streamable-http --host 0.0.0.0 --port 8000

See Installation and Deployment for the full matrix (PyPI extras, Docker image, all transports, agent server, reverse proxy, DNS).