Skip to content

Listmonk MCP Server

An MCP (Model Context Protocol) server for Listmonk, providing programmatic access to newsletter management through AI assistants and IDEs.

Features

  • Complete Listmonk API integration with async operations
  • Subscriber management (CRUD with query/pagination support)
  • List management with tags support
  • Campaign creation, management, and sending
  • Template management for campaigns and transactional messages
  • Transactional email sending with template data
  • Type-safe operations with Pydantic models

Installation

Install and run directly from PyPI:

# Run directly (installs if needed)
uvx listmonk-mcp --help

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

Using pip

pip install listmonk-mcp

Quick Start

  1. Install the server using uvx: 

    uvx install listmonk-mcp

  2. Create API credentials in Listmonk:

  3. Go to Listmonk Admin → Users

  4. Create a new API user and token

  5. Choose your setup:

  6. Claude Desktop - Claude Desktop app configuration
  7. VS Code - VS Code MCP settings
  8. Cline - Cline extension configuration
  9. Windsurf & Cursor - Windsurf and Cursor IDE setup

Configuration

All setups use the same basic configuration format:

{
  "command": "uv",
  "args": ["run", "python", "-m", "listmonk_mcp.server"],
  "cwd": "/path/to/listmonk-mcp",
  "env": {
    "LISTMONK_MCP_URL": "http://localhost:9000",
    "LISTMONK_MCP_USERNAME": "your-api-username", 
    "LISTMONK_MCP_PASSWORD": "your-api-token"
  }
}

API Coverage

The MCP server exposes 18 endpoints covering all major Listmonk operations:

  • Subscribers: Get, create, update, delete with advanced filtering
  • Lists: Full CRUD operations with tag support
  • Campaigns: Create, manage, and send campaigns
  • Templates: Access campaign and transactional templates
  • Transactional Messages: Send individual emails with template data

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. This server implements MCP to provide AI assistants with direct access to Listmonk's newsletter management capabilities.

Requirements

  • Python 3.11+
  • Running Listmonk instance
  • API credentials from Listmonk admin panel

📚 Documentation built with MkDocs Material