Listmonk MCP Server

A Model Context Protocol (MCP) server for integrating with Listmonk, the self-hosted newsletter and mailing list manager.

Features

This MCP server provides comprehensive tools for managing Listmonk through AI assistants:

Subscriber Management

• get_subscribers - Retrieve subscribers with filtering and pagination
• get_subscriber - Get details of a specific subscriber
• create_subscriber - Add new subscribers to lists
• update_subscriber - Modify subscriber information and list memberships
• delete_subscriber - Remove subscribers

Mailing List Management

• get_lists - Retrieve all mailing lists
• get_list - Get details of a specific mailing list
• create_list - Create new mailing lists (public/private)
• update_list - Modify list properties and settings
• delete_list - Remove mailing lists

Campaign Management

• get_campaigns - Retrieve campaigns with filtering
• get_campaign - Get details of a specific campaign
• create_campaign - Create new email campaigns with timezone-aware scheduling
• update_campaign_status - Change campaign status (draft, scheduled, running, etc.)
• delete_campaign - Remove campaigns

Template Management

• get_templates - Retrieve all email templates
• get_template - Get details of a specific template
• get_template_preview - Get HTML preview of a template
• create_template - Create new email templates
• update_template - Modify existing templates
• set_default_template - Set a template as default
• delete_template - Remove templates

Guided Workflows

The server includes helpful prompts for common workflows:

• manage_subscriber_lifecycle - Complete subscriber management guide
• create_campaign_workflow - Step-by-step campaign creation
• list_management_guide - Mailing list setup and management

Configuration

The server is configured through environment variables:

Required Variables

• LISTMONK_BASE_URL - Your Listmonk instance URL (e.g., http://localhost:9000)
• LISTMONK_API_KEY - Your Listmonk API key

Optional Variables

• LISTMONK_USERNAME - Basic Auth username (default: "api")
• LISTMONK_TIMEOUT - Request timeout in milliseconds (default: 30000)
• LISTMONK_RETRY_COUNT - Number of retries for failed requests (default: 3)

Setup

1. Listmonk API Key

First, create an API user in your Listmonk instance:

1. Go to your Listmonk admin panel
2. Navigate to Admin → Users
3. Create a new user with API permissions
4. Copy the generated API key

2. Environment Configuration

Create a .env file or set environment variables:

export LISTMONK_BASE_URL="http://localhost:9000"
export LISTMONK_API_KEY="your-api-key-here"
export LISTMONK_USERNAME="api"  # Optional, defaults to "api"
export LISTMONK_TIMEOUT="30000"
export LISTMONK_RETRY_COUNT="3"

3. Running the Server

Using Gradle

# Build the project
./gradlew build

# Run the server
./gradlew run

Using Docker (if Dockerfile is available)

docker build -t listmonk-mcp .
docker run -e LISTMONK_BASE_URL="http://localhost:9000" \
           -e LISTMONK_API_KEY="your-api-key" \
           -e LISTMONK_USERNAME="api" \
           listmonk-mcp

Usage with Claude Desktop

Add the server to your Claude Desktop configuration:

{
  "mcpServers": {
    "listmonk": {
      "command": "java",
      "args": ["-jar", "/path/to/listmonk-mcp-all.jar"],
      "env": {
        "LISTMONK_BASE_URL": "http://localhost:9000",
        "LISTMONK_API_KEY": "your-api-key-here",
        "LISTMONK_USERNAME": "api"
      }
    }
  }
}

Example Interactions

Creating a Subscriber

Use the create_subscriber tool to add a new subscriber:
- Email: john@example.com
- Name: John Doe
- Status: enabled
- Lists: [1, 2]

Creating a Campaign

Use the create_campaign tool to create a newsletter:
- Name: Monthly Newsletter
- Subject: O

... [View full README on GitHub](https://github.com/antoniolg/listmonk-mcp#readme)