# ListMonk MCP Server Setup Instructions

This package contains a Model Context Protocol (MCP) server for ListMonk, which allows AI assistants like Claude and Cursor to interact with your ListMonk email marketing instance.

## What's Included

- `dist/` - The compiled MCP server code
- `sdk/` - The ListMonk API SDK (Stainless-generated)
- `run-mcp-server.sh` - Script to run the server locally
- `Dockerfile` & `docker-compose.yml` - For Docker deployment
- `claude-desktop-config.json` - Example Claude Desktop configuration

## Prerequisites

- Node.js 18+ (for local running)
- Docker (for containerized deployment)
- A ListMonk instance with API access
- ListMonk admin credentials

## Quick Start

### Option 1: Run Locally

1. Set environment variables:
   ```bash
   export LISTMONK_BASE_URL="http://localhost:9000/api"
   export LISTMONK_USERNAME="admin"
   export LISTMONK_PASSWORD="your-password"
   ```

2. Run the server:
   ```bash
   ./run-mcp-server.sh
   ```

### Option 2: Run with Docker

1. Create a `.env` file:
   ```
   LISTMONK_BASE_URL=http://localhost:9000/api
   LISTMONK_USERNAME=admin
   LISTMONK_PASSWORD=your-password
   ```

2. Build and run:
   ```bash
   docker-compose up --build
   ```

### Option 3: Use with Claude Desktop

1. Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
   ```json
   {
     "mcpServers": {
       "listmonk": {
         "command": "node",
         "args": ["/absolute/path/to/listmonk-mcp-server-package/dist/index.js"],
         "env": {
           "LISTMONK_BASE_URL": "http://localhost:9000/api",
           "LISTMONK_USERNAME": "admin",
           "LISTMONK_PASSWORD": "your-password"
         }
       }
     }
   }
   ```

2. Restart Claude Desktop

## Available Tools

The MCP server provides these tools for interacting with ListMonk:

### Lists Management
- `listmonk_list_lists` - Get all lists
- `listmonk_create_list` - Create a new list (public/private, single/double opt-in)
- `listmonk_get_list` - Get a specific list
- `listmonk_update_list` - Update a list

### Subscribers Management
- `listmonk_list_subscribers` - Get all subscribers
- `listmonk_create_subscriber` - Create a new subscriber
- `listmonk_get_subscriber` - Get a specific subscriber
- `listmonk_update_subscriber` - Update a subscriber
- `listmonk_bulk_update_lists` - Bulk update subscriber list memberships

### Campaigns Management
- `listmonk_list_campaigns` - Get all campaigns
- `listmonk_create_campaign` - Create a new campaign
- `listmonk_get_campaign` - Get a specific campaign
- `listmonk_update_campaign_status` - Update campaign status
- `listmonk_send_test_campaign` - Send test campaign email

### Templates Management
- `listmonk_list_templates` - Get all templates
- `listmonk_create_template` - Create a new template

### Import Management
- `listmonk_import_subscribers` - Import subscribers from CSV

### Media Management
- `listmonk_list_media` - Get all media files
- `listmonk_upload_media` - Upload a media file

### Other
- `listmonk_update_settings` - Update ListMonk settings
- `listmonk_health_check` - Check API health status

## Troubleshooting

1. **Connection Issues**: Ensure your ListMonk instance is running and accessible. The API is usually at port 9000.

2. **Authentication**: ListMonk uses Basic Auth with admin credentials. Make sure your username and password are correct.

3. **API URL**: The base URL should point to your ListMonk API endpoint, typically `http://localhost:9000/api` for local instances.

4. **Docker Network**: If running ListMonk in Docker, ensure the MCP server can reach it (use Docker network names or host networking).

## Technical Details

- Built with TypeScript and the official MCP SDK
- Uses Stainless-generated ListMonk SDK for type-safe API interactions
- Supports all major ListMonk API operations
- Zero mock data - all operations go through the real ListMonk API

## Example Usage

Once connected to Claude or Cursor, you can:
- "Create a new mailing list called 'Newsletter' with double opt-in"
- "Show me all subscribers in the Marketing list"
- "Create a campaign for the Newsletter list"
- "Import subscribers from a CSV file"
- "Upload an image for use in campaigns"

## Security Notes

- Never commit your credentials to version control
- Use environment variables or secure credential storage
- Consider using a dedicated ListMonk user with appropriate permissions
- Be careful with bulk operations like imports

## ListMonk Configuration

Ensure your ListMonk instance:
1. Has API access enabled
2. Is accessible from where you're running the MCP server
3. Has appropriate CORS settings if needed