CaddyUI

An MCP server for CaddyUI — the self-hosted web UI for the Caddy reverse proxy. It lets an MCP client (Claude, etc.) inspect and manage your Caddy configuration in natural language: proxy hosts, redirection hosts, raw routes, and TLS certificates.

It wraps CaddyUI's stable, versioned REST API under /api/v1 (added in CaddyUI v2.13), authenticating with an API token (Authorization: Bearer <token>). CaddyUI's own SQLite DB is the source of truth; it pushes the generated config to Caddy's admin API — so this server talks to CaddyUI, not to Caddy directly.

Tools

Create/update tools take a JSON config object. The proxy-host model has 200+ optional fields, so the intended workflow is get_* an existing object, then modify and re-send — the server's instructions tell the LLM to do exactly that.

Multi-server

CaddyUI can centrally manage several Caddy instances, and every resource is scoped to one server. Almost every tool takes an optional server_id; omitting it targets CaddyUI's default server (1), which may be empty even when other servers are full. Call list_caddy_servers first — it probes the server ids and reports which hold proxy hosts (with sample domains so you can tell them apart) — then pass the chosen server_id to the other tools. (Server selection uses CaddyUI's caddyui_server cookie; there is no documented API parameter for it.)

Configuration

Config is via environment variables (12-factor). Copy .env.example to .env:

Getting a token

In CaddyUI, open API Tokens (/api-tokens), create a token with the scope you want, and copy it (shown once). For full read+write management, use full.

Run with Docker

cp .env.example .env       # then set CADDYUI_URL and CADDYUI_TOKEN
docker compose up -d --build
docker compose ps          # STATUS should become "healthy"

The server listens on :8080 and serves MCP over Streamable HTTP at http://<host>:8080/mcp. The container HEALTHCHECK performs a full MCP handshake and calls list_proxy_hosts, so it only reports healthy when CaddyUI is actually reachable and the token works (an empty CaddyUI still counts as healthy).

Once the registry image is published, pin it in compose.yaml:

image: ghcr.io/loryanstrant/caddyui-mcp:latest

Connect an MCP client

Point your client at the Streamable HTTP endpoint (note: /mcp, no trailing slash):

{
  "mcpServers": {
    "caddyui": { "type": "http", "url": "http://<host>:8080/mcp" }
  }
}

For a stdio client, run caddyui-mcp (instead of the web entrypoint) with the same env.

Develop

make install-dev   # venv + deps
make check         # lint + format-check + typecheck + test

# live tests against a real CaddyUI (creates and deletes a throwaway proxy host):
CADDYUI_URL=https://caddyui.example.com CADDYUI_TOKEN=cadu_... .venv/bin/pytest -m live

License

MIT.