Deploy Listmonk + MCP

Deploy and Host Listmonk + MCP on Railway

listmonk is a fast, self-hosted newsletter and mailing list manager. This template deploys listmonk together with PostgreSQL and the listmonk MCP server, so AI agents such as Claude, Cursor or ChatGPT can manage lists, subscribers, campaigns and templates over the Model Context Protocol. Everything is wired up on first boot: no setup wizard, no manual API user, no copy-pasting tokens.

About Hosting Listmonk + MCP

The template runs three services:

What happens on first boot:

1. listmonk waits for Postgres and runs --install --idempotent, creating the schema, a super admin (LISTMONK_ADMIN_USER / LISTMONK_ADMIN_PASSWORD) and an API user (LISTMONK_API_USER).
2. The API user's token is set to the generated LISTMONK_API_TOKEN. The MCP service reads the same variable through a reference variable, so it can talk to listmonk over the private network right away.
3. app.root_url is set to the public Railway domain, so links in emails point to the right place.
4. On every later start the install step is skipped, pending migrations run (--upgrade) and the API token is synced again. Changing LISTMONK_API_TOKEN and redeploying rotates the token.

All secrets (admin password, API token, MCP_AUTH_TOKEN, database password) are generated per deployment and can be found under Variables of each service. No secret is written to the logs.

Connect an MCP client

The MCP endpoint is https:// + the MCP service's public domain + /mcp (Streamable HTTP). Send MCP_AUTH_TOKEN as a Bearer token:

{
  "mcpServers": {
    "listmonk": {
      "url": "https://YOUR-MCP-DOMAIN.up.railway.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN" }
    }
  }
}

Claude Code CLI:

claude mcp add --transport http listmonk https://YOUR-MCP-DOMAIN.up.railway.app/mcp \
  --header "Authorization: Bearer YOUR_MCP_AUTH_TOKEN"

The server exposes 72 tools (subscribers, lists, campaigns, templates, media, imports, bounces, settings, transactional mail and more). Limit them with LISTMONK_ENABLED_TOOLS (for example subscribers,lists).

Sending email

listmonk needs an SMTP server to send campaigns. Configure it in the listmonk UI under Settings → SMTP (for example Amazon SES, Postmark, Resend, Brevo or your own server). Everything else, including the MCP tools, works before that.

Common Use Cases

• Let an AI agent create lists, import or clean up subscribers and draft campaigns for you
• Run a self-hosted newsletter for a product, blog or community without per-subscriber pricing
• Send transactional emails and manage opt-in lists from automations and chat-driven workflows

Dependencies for Listmonk + MCP Hosting

• An SMTP provider for sending email (Amazon SES, Postmark, Resend, Brevo or similar)
• An MCP-compatible client such as Cursor, Claude Desktop, Claude Code or another agent with Streamable HTTP support

Deployment Dependencies

• listmonk documentation
• mcp-listmonk – the MCP server used by this template
• Template source
• Model Context Protocol

Implementation Details

Postgres stores lists, subscribers and campaigns; the listmonk volume keeps uploaded media. Enable Railway volume backups for both before production use. Renovate keeps the listmonk and MCP image versions up to date, and redeploying runs listmonk's database migrations automatically.

Why Deploy Listmonk + MCP on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Listmonk + MCP on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.