---
title: "Deploy Listmonk + MCP"
description: "Self-hosted listmonk newsletters with Postgres and an MCP server for AI"
category: "AI/ML"
url: https://railway.com/deploy/listmonk-mcp
---

# Deploy Listmonk + MCP

Self-hosted listmonk newsletters with Postgres and an MCP server for AI

**[Deploy Listmonk + MCP on Railway](https://railway.com/template/listmonk-mcp)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/listmonk-mcp/manifest.json

- **Creator:** André Lademann's Projects
- **Category:** AI/ML

## Template content

### Listmonk

- **Source:** https://github.com/vergissberlin/railwayapp-listmonk-mcp
- **Health check:** /health
- **Public domain:** Yes

### MCP

- **Source:** https://github.com/vergissberlin/railwayapp-listmonk-mcp
- **Health check:** /healthz
- **Public domain:** Yes

### Postgres

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

## Documentation

# Deploy and Host Listmonk + MCP on Railway

![Listmonk + MCP](https://raw.githubusercontent.com/vergissberlin/railwayapp-listmonk-mcp/main/template-header.svg)

[listmonk](https://listmonk.app) is a fast, self-hosted newsletter and mailing list manager. This template deploys listmonk together with PostgreSQL and the [listmonk MCP server](https://github.com/kieksme/mcp-listmonk), 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:

| Service | Source | Public | Healthcheck | Volume |
|---------|--------|--------|-------------|--------|
| Postgres | `ghcr.io/railwayapp-templates/postgres-ssl:18` | no | built in | `/var/lib/postgresql/data` |
| Listmonk | listmonk v6 (official image + bootstrap script) | yes | `/health` | `/listmonk/uploads` |
| MCP | `ghcr.io/kieksme/mcp-listmonk` | yes | `/healthz` | none |

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:

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

Claude Code CLI:

```bash
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](https://listmonk.app/docs/)
- [mcp-listmonk](https://github.com/kieksme/mcp-listmonk) – the MCP server used by this template
- [Template source](https://github.com/vergissberlin/railwayapp-listmonk-mcp)
- [Model Context Protocol](https://modelcontextprotocol.io)

### 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.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [Weaviate](https://railway.com/deploy/weaviate-1) — Vector database with hybrid search and an API key-protected API
- [Möbius v0.1 Personal AI OS](https://railway.com/deploy/mobius-v01-personal-ai-os) — Self-hosted AI agent that builds and runs apps for you, with memory.

Open this page in a browser: https://railway.com/deploy/listmonk-mcp