Installation¶

listmonk-api is a standard Python package and a prebuilt container image. Choose the path that matches how you intend to run it.

Requirements¶

Python 3.10+.
A reachable Listmonk instance — see Backing Platform to deploy one locally with Docker.

From PyPI (recommended)¶

pip install listmonk-api

Optional extras¶

The base install ships the API client and the MCP server runtime. Install the extra for what you need:

Extra	Install	Pulls in
(base)	`pip install listmonk-api`	`agent-utilities[mcp]` — FastMCP MCP-server runtime
`agent`	`pip install "listmonk-api[agent]"`	Pydantic-AI agent + Logfire tracing
`all`	`pip install "listmonk-api[all]"`	Everything above (MCP + agent + Logfire)

# Typical: run the MCP server and the A2A agent
pip install "listmonk-api[all]"

From source¶

git clone https://github.com/Knuckles-Team/listmonk-api.git
cd listmonk-api
pip install -e ".[all]"          # editable install with every extra

With uv:

uv pip install -e ".[all]"
uv run listmonk-mcp

Prebuilt Docker image¶

A multi-stage, slim image is published on every release (entrypoint listmonk-mcp):

docker pull knucklessg1/listmonk-api:latest

docker run --rm -i \
  -e LISTMONK_URL=https://listmonk.yourdomain.com \
  -e LISTMONK_TOKEN=your-bearer-token \
  knucklessg1/listmonk-api:latest        # stdio transport (default)

For an HTTP server with a published port and the agent server, see Deployment.

Verify the install¶

listmonk-mcp --help
python -c "import listmonk_api; print(listmonk_api.__version__)"

Next steps¶

Deployment — run it as a long-lived MCP server and agent behind Caddy + DNS.
Usage — call the tools, the API, and the agent CLI.
Configuration — every environment variable.