CaddyUI MCP

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.

Check before you write. test_upstream confirms a backend is reachable before you point a proxy host at it; validate_raw_route confirms a raw route parses before you save it (otherwise errors only surface at the next Caddy sync); check_deploy_status reports afterwards whether DNS propagated and the certificate was issued. All three are read-only.

Certificates

source is one of pem (inline cert_pem/key_pem), path (cert_path/key_path on the Caddy host), or managed — ACME DNS-01, including standalone wildcards, added in CaddyUI 2.17. A managed certificate needs dns_provider (and usually dns_profile_id), whose credentials must already be saved in CaddyUI's Settings.

Worth knowing: CaddyUI does not validate source and silently defaults it to pem; list_certificates returns managed entries mixed in with the rest (the web UI's dropdowns hide them, the API does not); update_certificate is a partial merge that ignores empty strings, so a field cannot be blanked; and delete_certificate returns 409 while anything still references the certificate. find_unused_certificates shows what is safe to remove.

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 lists the registered servers and probes ids 1..probe_max for orphaned leftovers from deleted servers, reporting host counts and 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.)

Each entry also reports type, caddy_version, tags and last_contact_at. type is a safety signal worth reading: managed means CaddyUI validates and pushes config to that Caddy instance, while external means it only monitors it — a write there is stored in CaddyUI's database and returns success, but never reaches Caddy.

Server details come from GET /api/v1/servers, which CaddyUI added in v2.20.2 at this project's request (upstream issue #18). It isn't admin-gated, so a read_only token now sees full server names — the HTML page it replaced was. On CaddyUI older than 2.20.2 the client falls back to parsing that HTML page; that path is deprecated and scheduled for removal (see DECISIONS.md).

Related MCP server: npm-mcp

Compatibility

Works against CaddyUI 2.13+ (when /api/v1 was introduced), but 2.20.2 or newer is recommended — that's the first release with everything this server uses. On older instances:

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

Stateless by default

The web entrypoint runs stateless: a new transport per request, with no session store.

In FastMCP's default stateful mode every MCP initialize parks a transport (plus two suspended tasks) in the session manager, and only a client DELETE or an idle timeout evicts it. In practice neither happens — MCP clients rarely send DELETE, the SDK skips its own cleanup for the sessions that do get one, and FastMCP never enables the SDK's idle timeout. This server leaked 51,547 sessions in 14 days, about 4.6 GB of RAM, three quarters of it caused by its own healthcheck. DECISIONS.md (2026-08-30) has the measurements.

Two consequences, both deliberate:

• GET /mcp returns 405 and no mcp-session-id header is issued. That is the standard stateless topology; both official MCP SDKs treat a 405 there as benign and continue without the stream. All 35 tools are plain request/response, so nothing is ever pushed to a client.

• Don't add a tool that needs server→client messaging (a Context parameter, progress, sampling, elicitation, or a resource subscription) without revisiting this. tests/test_http_session_lifecycle.py fails if you do.

Set MCP_STATELESS_HTTP=0 to restore the stateful transport. That reintroduces the leak, so treat it purely as a rollback lever.

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.