Listmonk MCP Server

<p align="center">

</p>

Overview

This project provides a Model Context Protocol (MCP) server designed to interact with a Listmonk instance. It allows users of Cline (or other MCP-compatible clients) to manage their Listmonk mailing lists, subscribers, campaigns, and more directly through the MCP interface.

This server acts as a bridge, translating MCP requests into Listmonk API calls.

Benefits

Integrate Listmonk with Cline: Seamlessly manage Listmonk resources and actions within your Cline workflow.
Automate Email Marketing Tasks: Script and automate common Listmonk operations like adding subscribers, managing lists, or checking campaign stats.
Centralized Management: Interact with Listmonk alongside other tools and services connected via MCP.

Subscribers:
get_subscriber(subscriber_id)
list_subscribers(query, list_id, status, page, per_page)
create_subscriber(email, name, status, lists, attribs, preconfirm)
update_subscriber(subscriber_id, email, name, status, lists, attribs)
delete_subscriber(subscriber_id)
blocklist_subscriber(subscriber_id)
manage_subscriber_lists(subscriber_ids, action, list_ids, status)
Lists:
get_list(list_id)
list_lists(query, status, tag, page, per_page)
create_list(name, type, optin, tags, description)
update_list(list_id, name, type, optin, tags, description)
delete_list(list_id)

Campaigns:
get_campaign(campaign_id, no_body=False): Retrieves campaign details (includes basic stats like views, clicks, sent count).
list_campaigns(query=None, status=None, tags=None, page=1, per_page=100, no_body=False)
create_campaign(name, subject, lists, type, content_type, body, from_email=None, altbody=None, send_at=None, messenger=None, template_id=None, tags=None, headers=None)
update_campaign(campaign_id, name=None, subject=None, lists=None, ...): Updates specified fields of a campaign.
delete_campaign(campaign_id)
change_campaign_status(campaign_id, status)

Templates:
list_templates()
get_template(template_id)
preview_template(template_id)
create_template(name, type, body, subject=None)
update_template(template_id, name=None, type=None, body=None, subject=None)
set_default_template(template_id)
delete_template(template_id)
render_template_preview(body, type, subject=None)

Bounces:
list_bounces(campaign_id=None, page=None, per_page=None, source=None, order_by=None, order=None)
delete_bounces(ids=None, all=None)
delete_bounce(bounce_id)
Transactional:
send_transactional_message(template_id, subscriber_email=None, subscriber_id=None, subscriber_emails=None, subscriber_ids=None, from_email=None, data=None, headers=None, messenger=None, content_type=None): Sends a message using a transactional template.

1. Prerequisites:
A running Listmonk instance.
Python 3.x installed.
2. Installation:
Clone this repository (or obtain the packaged server).
Navigate to the server directory.
Set up a Python virtual environment:

        python3 -m venv venv

        source venv/bin/activate  # Linux/macOS

        # or .\venv\Scripts\activate # Windows

        

        pip install -r requirements.txt

        

    # .env

    LISTMONK_API_ENDPOINT="https://your-listmonk-instance.com/api"

    LISTMONK_API_USER="your_api_username"

    LISTMONK_API_TOKEN="your_api_password_or_token"

    

Example cline_mcp_settings.json entry:

    {

      "mcpServers": {

        "listmonk": {

          "command": "python",

          "args": ["/path/to/listmonk-mcp/src/main.py"],

          "env": {

            "LISTMONK_API_ENDPOINT": "YOUR_LISTMONK_API_URL",

            "LISTMONK_API_USER": "YOUR_API_USERNAME",

            "LISTMONK_API_TOKEN": "YOUR_API_TOKEN"

          },

          "disabled": false,

          "autoApprove": []

        }

      }

    }

    

Usage / Tutorial (Example MCP Tool Calls)

Once the server is implemented and configured, you could use tools like this (syntax may vary based on the MCP client):

List Subscribers:

{

  "tool_name": "list_subscribers",

  "arguments": {

    "per_page": 10

  }

}

Create a Subscriber:

{

  "tool_name": "create_subscriber",

  "arguments": {

    "email": "new.subscriber@example.com",

    "name": "New Subscriber",

    "status": "enabled",

    "lists": [3, 4],

    "preconfirm": true

  }

}

Get Campaign Details:

{

  "tool_name": "get_campaign",

  "arguments": {

    "campaign_id": 5

  }

}

Development

This server is built using Python. Key dependencies include:

requests: For making HTTP calls to the Listmonk API.
python-dotenv: For loading environment variables from a .env file.

The code structure organizes tool handlers by resource type:

src/main.py: Main server entry point, loads configuration, and handles MCP request routing.
src/client.py: Centralized helper for making authenticated API requests.
src/subscribers.py: Logic for subscriber-related tools.
src/lists.py: Logic for list-related tools.
src/campaigns.py: Logic for campaign-related tools.
src/templates.py: Logic for template-related tools.
src/bounces.py: Logic for bounce-related tools.
src/transactional.py: Logic for transactional message tools.