@kieksme/listmonk-mcp

MCP 호환 LLM 클라이언트에 Listmonk REST API 전체(14개 카테고리, 72개 도구)를 노출하는 MCP(Model Context Protocol) 서버입니다. 클라이언트가 직접 생성하는 로컬 stdio 프로세스로 실행하거나, 여러 클라이언트가 연결할 수 있는 원격 Streamable HTTP 배포로 실행할 수 있습니다.

Listmonk OpenAPI 스펙을 기반으로 제작되었습니다.

빠른 시작

로컬: MCP 클라이언트가 stdio를 통해 서버를 직접 생성하게 하세요. 직접 실행할 것도, 열어야 할 포트도 없습니다. 클라이언트 구성에 추가하세요(여기서는 Claude Code를 예로 듭니다. Cursor, VS Code, Claude Desktop, OpenCode, LM Studio, ChatGPT용 구성은 아래 MCP 클라이언트 연결을 참조하세요):

claude mcp add listmonk \
  -e LISTMONK_URL=https://newsletter.example.com \
  -e LISTMONK_API_USER=my-api-user \
  -e LISTMONK_API_TOKEN=xxxxxxxx \
  -- npx -y @kieksme/listmonk-mcp --stdio

원격: 서버를 한 번 시작하면 여러 클라이언트가 HTTP로 연결할 수 있습니다:

LISTMONK_URL=https://newsletter.example.com \
LISTMONK_API_USER=my-api-user \
LISTMONK_API_TOKEN=xxxxxxxx \
npx @kieksme/listmonk-mcp

claude mcp add --transport http listmonk http://localhost:3000/mcp

두 모드에 대한 자세한 내용은 서버 실행을 참조하세요(Docker 포함).

Related MCP server: listmonk-mcp-bridge

MCP 클라이언트 연결

아래 각 클라이언트는 두 가지 설정을 지원합니다. 하나를 선택하세요:

• 로컬(stdio): 클라이언트가 npx @kieksme/listmonk-mcp --stdio를 하위 프로세스로 직접 생성하고 stdin/stdout으로 MCP를 통신합니다. 계속 실행할 서버도, 포트도, 연결 가능성 문제도 없습니다. 일반적으로 단일 로컬 클라이언트에는 이 방식이 더 간단한 기본값입니다.

• 원격(HTTP): 서버를 직접 실행하고(서버 실행 참조) 클라이언트가 해당 URL에 연결합니다. 여러 클라이언트가 하나의 서버 인스턴스를 공유하거나, 서버가 내 컴퓨터가 아닌 다른 곳에서 실행될 때 필요합니다.

로컬/stdio 설정에서 npx 대신 pnpm 사용하기: 아래 모든 로컬(stdio) 예시는 command: "npx"와 args: ["-y", "@kieksme/listmonk-mcp", "--stdio"]를 사용합니다. pnpm을 선호한다면 command: "pnpm"과 args: ["dlx", "@kieksme/listmonk-mcp", "--stdio"]로 바꾸세요. 단, -y는 제거하세요. -y는 npx의 "설치 확인 프롬프트 건너뛰기" 플래그입니다. pnpm dlx에는 애초에 그런 프롬프트가 없으므로 -y를 전혀 받지 않으며, ERROR Unknown option: 'y'를 출력하고 즉시 종료됩니다(프로세스가 MCP와 통신하기 전에 죽으므로 클라이언트에는 일반적인 "Connection closed"로 표시됩니다). 아래에서 npx -y로 시작하는 모든 CLI 형식에도 동일한 교체가 적용됩니다. pnpm dlx로 바꾸세요(-y 없이).

원격/HTTP 설정의 연결 가능성 참고: 클라이언트가 서버와 같은 머신에서 실행되는 경우에만 http://localhost:3000이 필요합니다. Claude Code, Cursor, VS Code, OpenCode, LM Studio는 모두 로컬 도구이므로 localhost가 바로 작동합니다. Claude Desktop도 로컬 앱이며 일반적으로 localhost에 연결할 수 있습니다. ChatGPT와 Claude.ai(웹 앱)는 클라우드에서 실행되므로 사용자의 localhost에 연결할 수 없습니다. 이 서버를 이들과 함께 사용하려면 인터넷에서 접근 가능한 곳에 배포하거나(예: ngrok http 3000으로 터널링) 공개 URL을 사용해야 합니다. ChatGPT의 커넥터는 HTTP 전용이므로 아래에 로컬/stdio 옵션이 없습니다.

Claude Code

로컬(stdio), 저장소 루트의 .mcp.json을 통한 프로젝트 범위 설정:

{
  "mcpServers": {
    "listmonk": {
      "command": "npx",
      "args": ["-y", "@kieksme/listmonk-mcp", "--stdio"],
      "env": {
        "LISTMONK_URL": "https://newsletter.example.com",
        "LISTMONK_API_USER": "my-api-user",
        "LISTMONK_API_TOKEN": "xxxxxxxx"
      }
    }
  }
}

또는 CLI에서:

claude mcp add listmonk \
  -e LISTMONK_URL=https://newsletter.example.com \
  -e LISTMONK_API_USER=my-api-user \
  -e LISTMONK_API_TOKEN=xxxxxxxx \
  -- npx -y @kieksme/listmonk-mcp --stdio

원격(HTTP), 서버가 실행 중일 때(서버 실행 참조):

{
  "mcpServers": {
    "listmonk": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

claude mcp add --transport http listmonk http://localhost:3000/mcp

서버에서 MCP_SERVER_AUTH_TOKEN을 설정한 경우 다음 헤더를 추가하세요: claude mcp add --transport http listmonk http://localhost:3000/mcp --header "Authorization: Bearer <token>".

Cursor

원클릭 설치(로컬/stdio, 이후 Cursor의 MCP 설정에서 채워야 하는 자리 표시자 자격 증명 포함):

또는 수동으로 구성할 수 있습니다. 저장소 루트의 .cursor/mcp.json(또는 전역 ~/.cursor/mcp.json)을 통한 로컬(stdio) 설정:

{
  "mcpServers": {
    "listmonk": {
      "command": "npx",
      "args": ["-y", "@kieksme/listmonk-mcp", "--stdio"],
      "env": {
        "LISTMONK_URL": "https://newsletter.example.com",
        "LISTMONK_API_USER": "my-api-user",
        "LISTMONK_API_TOKEN": "xxxxxxxx"
      }
    }
  }
}

원격(HTTP), 서버가 실행 중일 때:

{
  "mcpServers": {
    "listmonk": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

서버에서 MCP_SERVER_AUTH_TOKEN을 설정한 경우 헤더로 전달하세요:

{
  "mcpServers": {
    "listmonk": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

또한 Cursor 설정 → MCP → 새 MCP 서버 추가를 통해 두 설정 중 하나를 추가할 수 있습니다.

VS Code

원클릭 설치(로컬/stdio, 이후 VS Code의 MCP 설정에서 채워야 하는 자리 표시자 자격 증명 포함):

또는 수동으로 구성할 수 있습니다. 저장소 루트의 .vscode/mcp.json을 통한 로컬(stdio) 설정:

{
  "servers": {
    "listmonk": {
      "command": "npx",
      "args": ["-y", "@kieksme/listmonk-mcp", "--stdio"],
      "env": {
        "LISTMONK_URL": "https://newsletter.example.com",
        "LISTMONK_API_USER": "my-api-user",
        "LISTMONK_API_TOKEN": "xxxxxxxx"
      }
    }
  }
}

원격(HTTP), 서버가 실행 중일 때(여기서는 command가 없어 유추할 수 없으므로 type이 필요합니다):

{
  "servers": {
    "listmonk": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Claude Desktop

로컬(stdio), claude_desktop_config.json에서:

{
  "mcpServers": {
    "listmonk": {
      "command": "npx",
      "args": ["-y", "@kieksme/listmonk-mcp", "--stdio"],
      "env": {
        "LISTMONK_URL": "https://newsletter.example.com",
        "LISTMONK_API_USER": "my-api-user",
        "LISTMONK_API_TOKEN": "xxxxxxxx"
      }
    }
  }
}

원격(HTTP): Settings → Connectors → Add custom connector로 이동하여 URL로 http://localhost:3000/mcp를 붙여넣으세요(서버가 이미 실행 중이어야 합니다). 사용 중인 Claude Desktop 버전의 구성 파일이 원격 서버를 직접 지원한다면, 해당 항목은 다음과 같습니다:

{
  "mcpServers": {
    "listmonk": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

OpenCode

로컬(stdio), opencode.json(프로젝트 또는 전역 구성)에서:

{
  "mcp": {
    "listmonk": {
      "type": "local",
      "command": ["npx", "-y", "@kieksme/listmonk-mcp", "--stdio"],
      "environment": {
        "LISTMONK_URL": "https://newsletter.example.com",
        "LISTMONK_API_USER": "my-api-user",
        "LISTMONK_API_TOKEN": "xxxxxxxx"
      },
      "enabled": true
    }
  }
}

원격(HTTP), 서버가 실행 중일 때:

{
  "mcp": {
    "listmonk": {
      "type": "remote",
      "url": "http://localhost:3000/mcp",
      "enabled": true
    }
  }
}

enabled에 대한 참고: 이 플래그는 OpenCode 자체의 클라이언트 측 스위치입니다. 해당 클라이언트에서 전체 서버 연결을 켜고 끌 뿐이며, 어떤 listmonk 도구/카테고리가 노출되는지와는 무관합니다. 원격(HTTP) 설정에서 특정 클라이언트가 보는 도구를 제한하려면(서버를 재시작하거나 LISTMONK_ENABLED_TOOLS를 건드리지 않고) url 자체에 tools 쿼리 매개변수를 추가하세요:

{
  "mcp": {
    "listmonk": {
      "type": "remote",
      "url": "http://localhost:3000/mcp?tools=subscribers,campaigns",
      "enabled": true
    }
  }
}

로컬(stdio) 설정에서는 대신 environment에 LISTMONK_ENABLED_TOOLS를 설정하세요. 전체 선택기 구문은 사용 가능한 도구 선택을 참조하세요.

LM Studio

원클릭 설치(로컬/stdio, 이후 LM Studio의 MCP 설정에서 채워야 하는 자리 표시자 자격 증명 포함):

또는 ~/.lmstudio/mcp.json을 통해 수동으로 구성할 수 있습니다(Program 탭 → Install → Edit mcp.json) — 로컬(stdio):

{
  "mcpServers": {
    "listmonk": {
      "command": "npx",
      "args": ["-y", "@kieksme/listmonk-mcp", "--stdio"],
      "env": {
        "LISTMONK_URL": "https://newsletter.example.com",
        "LISTMONK_API_USER": "my-api-user",
        "LISTMONK_API_TOKEN": "xxxxxxxx"
      }
    }
  }
}

원격(HTTP), 서버가 실행 중일 때:

{
  "mcpServers": {
    "listmonk": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

ChatGPT

ChatGPT의 커넥터(Settings → Connectors → Create, MCP를 지원하는 유료 요금제에서 사용 가능)는 공개적으로 접근 가능한 HTTP URL만 허용합니다. ChatGPT는 클라우드에서 실행되므로 로컬 stdio 프로세스를 생성할 수 없으며, 따라서 원격 설정이 유일한 옵션입니다. 서버를 공개 URL이 있는 호스트에 배포하거나(Docker 참조) 로컬 인스턴스를 터널링한 다음(예: ngrok http 3000) https://<your-host>/mcp를 커넥터 URL로 등록하세요. MCP_SERVER_AUTH_TOKEN을 설정한 경우 ChatGPT의 커넥터 설정에서 URL과 함께 베어러 토큰을 제공할 수 있습니다.

기능

• 전체 API 지원: 구독자, 캠페인, 목록, 템플릿, 미디어, 반송, 가져오기, 설정, 유지 관리, 트랜잭션 메시지, 공개 구독, 로그, 관리자, 대시보드/기타 엔드포인트.

• 선택적 도구 로딩 — 실제로 필요한 카테고리/도구만 활성화하여 LLM 컨텍스트가 한 번에 72개 도구 정의로 넘치지 않게 합니다.

• 하나의 패키지, 두 가지 전송 방식: 클라이언트가 생성하는 로컬 프로세스용 stdio, 원격 배포용 무상태 Streamable HTTP(세션 상태 없음, 로드 밸런서 뒤에서 수평 확장 용이).

• /mcp 앞의 선택적 베어러 토큰 게이트(HTTP 전송 전용 — stdio에는 게이트할 네트워크 리스너가 없습니다).

서버 실행

로컬(stdio)

일반적으로 이 서버를 직접 시작할 필요는 없습니다. MCP 클라이언트가 위의 MCP 클라이언트 연결 구성에 따라 서버를 생성합니다. 수동으로 실행하려면(예: 클라이언트 외부에서 제대로 작동하는지 확인하려면) --stdio를 전달하거나 MCP_TRANSPORT=stdio를 설정하세요:

LISTMONK_URL=https://newsletter.example.com \
LISTMONK_API_USER=my-api-user \
LISTMONK_API_TOKEN=xxxxxxxx \
npx @kieksme/listmonk-mcp --stdio

이 프로세스는 stdout에서 MCP JSON-RPC를 사용하고 stderr로 로그를 출력합니다. stdin이 닫히면(즉, 상위 클라이언트가 연결을 끊으면) 종료됩니다. LISTMONK_ENABLED_TOOLS는 여전히 등록할 도구를 선택하지만, 이 모드에서는 요청별 재정의가 없습니다. 클라이언트 프로세스 하나에 수명 동안 고정된 도구 집합 하나입니다.

원격(HTTP)

LISTMONK_URL=https://newsletter.example.com \
LISTMONK_API_USER=my-api-user \
LISTMONK_API_TOKEN=xxxxxxxx \
npx @kieksme/listmonk-mcp
# or
pnpm dlx @kieksme/listmonk-mcp

MCP 엔드포인트는 POST http://localhost:3000/mcp입니다(streamable HTTP, 무상태 — 세션 협상 불필요).

Docker

게시된 이미지(ghcr.io/kieksme/mcp-listmonk:latest)는 두 전송 방식을 모두 지원합니다. npx와 동일한 엔트리포인트이므로 위의 플래그가 동일하게 적용됩니다.

원격(HTTP) — 포트를 게시하세요:

docker run -p 3000:3000 \
  -e LISTMONK_URL=https://newsletter.example.com \
  -e LISTMONK_API_USER=my-api-user \
  -e LISTMONK_API_TOKEN=xxxxxxxx \
  -e LISTMONK_ENABLED_TOOLS='["subscribers","campaigns"]' \
  ghcr.io/kieksme/mcp-listmonk:latest

로컬(stdio) — 포트를 게시하는 대신 stdin을 연결된 상태로 유지하세요(-i). npx가 패키지를 가져오는 대신 컨테이너를 실행하려는 경우 클라이언트의 command/args(예: command를 docker로) 뒤에 넣는 방식입니다:

docker run -i --rm \
  -e LISTMONK_URL=https://newsletter.example.com \
  -e LISTMONK_API_USER=my-api-user \
  -e LISTMONK_API_TOKEN=xxxxxxxx \
  ghcr.io/kieksme/mcp-listmonk:latest --stdio

구성

서버를 시작할 때 다음 환경 변수를 설정하세요:

보안 참고: LISTMONK_API_USER/LISTMONK_API_TOKEN은 이 서버를 Listmonk에 인증하는 것이지, MCP 클라이언트를 이 서버에 인증하는 것이 아닙니다. MCP_SERVER_AUTH_TOKEN이 없으면 포트에 도달할 수 있는 사람은 누구나 구성된 API 사용자가 가진 범위 내에서 Listmonk에 대한 전체 액세스 권한을 얻습니다. Listmonk에서 활성화하려는 카테고리에만 범위가 제한된 최소 권한 API 사용자를 만드는 것이 좋습니다.

사용 가능한 도구 선택

LISTMONK_ENABLED_TOOLS는 JSON 배열(또는 쉼표로 구분된 문자열)을 허용하며, 항목은 대소문자를 구분하지 않고 다음 중 하나입니다:

• 카테고리 이름: subscribers, campaigns, templates, lists, media, import, bounces, settings, maintenance, public, transactional, logs, admin, miscellaneous — 해당 카테고리의 모든 도구를 활성화하거나,

• 정확한 도구 이름: 예: listmonk_get_subscriber — 해당 도구 하나만 활성화합니다.

# Only subscriber management tools
LISTMONK_ENABLED_TOOLS='["subscribers"]'

# A mix of a whole category plus one extra tool
LISTMONK_ENABLED_TOOLS='["campaigns","listmonk_get_health"]'

# Comma-separated form also works
LISTMONK_ENABLED_TOOLS=subscribers,campaigns

설정하지 않은 채로 두면(또는 []) 72개 도구가 모두 노출됩니다.

요청별 재정의(원격/HTTP 전용): 단일 배포 인스턴스는 재시작 없이도 POST /mcp 요청의 X-Listmonk-Enabled-Tools 헤더 또는 ?tools= 쿼리 문자열을 통해 클라이언트마다 다른 도구 세트를 제공할 수 있습니다 — 선택기 구문은 위와 동일합니다. 이는 해당 요청 하나에 대해서만 LISTMONK_ENABLED_TOOLS를 재정의합니다. 로컬/stdio 전송에는 이에 상응하는 기능이 없습니다. 각 stdio 프로세스는 클라이언트마다 새로 생성되므로, 대신 해당 클라이언트 자체의 env/environment 구성에 LISTMONK_ENABLED_TOOLS를 설정하면 됩니다.

쿼리 문자열은 URL의 일부일 뿐이므로, 특정 클라이언트(예: opencode.json, .mcp.json 또는 .cursor/mcp.json의 항목 하나)에게는 축소된 도구 세트를 제공하면서 다른 클라이언트는 동일한 서버에 전체(또는 다른) 세트로 계속 접근하게 하려는 경우 이 방법이 가장 쉽습니다 — 서버 전체 환경 변수를 추가하거나 두 번째 인스턴스를 띄우는 대신 해당 클라이언트의 url을 http://localhost:3000/mcp?tools=subscribers,campaigns로 설정하기만 하면 됩니다. 사용자 지정 헤더를 지원하는 클라이언트는 X-Listmonk-Enabled-Tools를 대신 사용할 수 있으며, 이렇게 하면 URL 자체가 깔끔하게 유지됩니다.

도구 카탈로그 (72개 도구)

subscribers (17)

listmonk_list_subscribers, listmonk_create_subscriber, listmonk_get_subscriber, listmonk_update_subscriber, listmonk_delete_subscriber, listmonk_delete_subscribers_by_ids, listmonk_manage_subscriber_lists_bulk, listmonk_manage_subscriber_list_membership, listmonk_blocklist_subscribers_bulk, listmonk_blocklist_subscriber, listmonk_export_subscriber, listmonk_get_subscriber_bounces, listmonk_delete_subscriber_bounces, listmonk_send_subscriber_optin, listmonk_delete_subscribers_by_query, listmonk_blocklist_subscribers_by_query, listmonk_manage_subscriber_lists_by_query

campaigns (14)

listmonk_list_campaigns, listmonk_create_campaign, listmonk_get_campaign, listmonk_update_campaign, listmonk_delete_campaign, listmonk_get_running_campaign_stats, listmonk_get_campaign_analytics, listmonk_get_campaign_preview, listmonk_preview_campaign_draft, listmonk_preview_campaign_text, listmonk_update_campaign_status, listmonk_update_campaign_archive, listmonk_convert_campaign_content, listmonk_send_campaign_test

templates (8)

listmonk_list_templates, listmonk_create_template, listmonk_get_template, listmonk_update_template, listmonk_delete_template, listmonk_preview_template_draft, listmonk_preview_template, listmonk_set_default_template

lists (5)

listmonk_list_lists, listmonk_create_list, listmonk_get_list, listmonk_update_list, listmonk_delete_list

media (4)

listmonk_list_media, listmonk_upload_media, listmonk_get_media, listmonk_delete_media

import (4)

listmonk_get_import_status, listmonk_import_subscribers, listmonk_stop_import_subscribers, listmonk_get_import_logs

bounces (4)

listmonk_list_bounces, listmonk_delete_bounces, listmonk_get_bounce, listmonk_delete_bounce

settings (3)

listmonk_get_settings, listmonk_update_settings, listmonk_test_smtp_settings

maintenance (3)

listmonk_delete_gc_subscribers, listmonk_delete_gc_campaign_analytics, listmonk_delete_unconfirmed_subscriptions

public (2)

listmonk_get_public_lists, listmonk_create_public_subscription

transactional (1)

listmonk_send_transactional_message

logs (1)

listmonk_get_logs

admin (1)

listmonk_reload_app

miscellaneous (5)

listmonk_get_health, listmonk_get_server_config, listmonk_get_i18n_lang, listmonk_get_dashboard_charts, listmonk_get_dashboard_counts

몇 가지 비직관적인 도구에 대한 참고 사항

• 대량/쿼리 구독자 작업 (listmonk_delete_subscribers_by_query, listmonk_blocklist_subscribers_by_query, listmonk_manage_subscriber_lists_by_query)은 Listmonk SQL 필터 표현식을 대상으로 실행되며 미리 보기 단계 없이 일치하는 모든 구독자에게 적용됩니다. 항상 동일한 query로 listmonk_list_subscribers를 먼저 호출하여 일치 개수를 확인하세요.

• 캠페인 미리 보기/콘텐츠 도구는 Listmonk가 이들을 위해 네 개의 서로 다른 엔드포인트를 노출하기 때문에 의도적으로 네 개의 별도 도구로 나뉘어 있습니다: listmonk_get_campaign_preview는 현재 저장된 대로 캠페인을 렌더링합니다. listmonk_preview_campaign_draft와 listmonk_preview_campaign_text는 아무것도 저장하지 않고 저장되지 않은 본문을 렌더링합니다. listmonk_convert_campaign_content는 형식 변환(예: markdown → HTML)을 수행하고 저장합니다 — 비슷한 영역이지만 미리 보기가 아닙니다.

• **listmonk_send_campaign_test**는 먼저 캠페인의 현재 저장된 상태를 가져온 다음 명시적으로 전달한 필드만 재정의하여, Listmonk 자체 API가 그렇지 않으면 빈 값으로 조용히 덮어쓸 필드가 실수로 비워지는 것을 방지합니다.

기여

소스에서 빌드하거나, 테스트 스위트를 실행하거나, 릴리스 프로세스를 이해하고 싶으신가요? CONTRIBUTING.md를 참조하세요.

라이선스

MIT © kieksme GbR