Skip to main content
Glama

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

Resource

Tools

Servers

list_caddy_servers

Proxy hosts

list_proxy_hosts, get_proxy_host, create_proxy_host, update_proxy_host, delete_proxy_host, toggle_proxy_host, set_proxy_host_maintenance

Redirection hosts

list_redirection_hosts, get_redirection_host, create_redirection_host, update_redirection_host, delete_redirection_host, toggle_redirection_host

Raw routes

list_raw_routes, get_raw_route, create_raw_route, update_raw_route, delete_raw_route, toggle_raw_route

Certificates

list_certificates, get_certificate, create_certificate, update_certificate, delete_certificate, find_unused_certificates, managed_certificate_status

Status (read-only)

caddy_version, caddyui_version, system_stats, upstream_health, search

Pre-flight / diagnostics (read-only)

test_upstream, validate_raw_route, check_deploy_status

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:

Below

What degrades

2.20.2

Server details fall back to scraping the admin-gated HTML page, so tags and last_contact_at are unavailable and a non-admin token yields no server names. caddyui_version's latest field is unreliable (#17).

2.17.2

managed_certificate_status returns an error (the endpoint doesn't exist).

2.17.0

No managed (ACME DNS-01) certificate source; no dns_provider / dns_profile_id fields.

Configuration

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

Variable

Required

Description

CADDYUI_URL

yes

CaddyUI base URL, e.g. https://caddyui.example.com (default https://caddyui.strant.casa).

CADDYUI_TOKEN

yes

API token minted in CaddyUI at /api-tokens. Scope full (all CRUD), proxy_write (proxy hosts only), or read_only.

MCP_HTTP_PORT

no

Port for the web entrypoint (default 8080).

MCP_ALLOWED_HOSTS

no

Comma-separated Host allow-list for the web entrypoint's DNS-rebinding protection (default *.strant.casa).

MCP_STATELESS_HTTP

no

Serve Streamable HTTP statelessly (default true). See Stateless by default — set 0 only to roll back.

LOG_LEVEL

no

DEBUG/INFO/WARNING/ERROR (default INFO).

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    • Hostelworld MCP server for ChatGPT, Claude and any AI agent: list reservations, reply to review, reply to guest and get payouts report in your own Hostelworld account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Hostelworld yourself; Cotlet does not store your password and you need no Hostelworld API key. About the official Hostelworld API: Hostelworld has no public API for property owners (checked 11 Oct 2026). Its affiliate programme offers an API for property and destination information "on a case by case basis", and properties sync rates, availability and bookings only through an integrated channel manager. Setup and FAQ: https://cotlet.dev/integrations/hostelworld-api-mcp-server

    • Hostfully MCP server for ChatGPT, Claude and any AI agent: list reservations, get reservation, accept booking request, send guest message, read Central Calendar and list properties in your own Hostfully account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Hostfully yourself; Cotlet does not store your password and you need no Hostfully API key. About the official Hostfully API: Hostfully has an official REST API, the Open API v3, and no official MCP server (checked 31 Oct 2026). It is a paid add-on: you email api@hostfully.com with your use case, test in a sandbox, and only then get production access. Setup and FAQ: https://cotlet.dev/integrations/hostfully-api-mcp-server

    • Toast MCP server for ChatGPT, Claude and any AI agent: list menus, list menu items, 86 a menu item, set menu hours, get sales summary, list time entries, fix time entry and create shift in your own Toast account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Toast yourself; Cotlet does not store your password and you need no Toast API key. About the official Toast API: Toast has an API, but the access a restaurant creates for itself is read-only (checked 28 Oct 2026). Standard API access needs Restaurant Management Suite (RMS) Essentials or higher and the Manage Integrations permission, and it cannot write. Setup and FAQ: https://cotlet.dev/integrations/toast-api-mcp-server

      https://cotlet.dev/mcp/v1/toast
    • Little Hotelier MCP server for ChatGPT, Claude and any AI agent: list bookings, update rates, update availability, create booking, message guest and get occupancy report in your own Little Hotelier account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Little Hotelier yourself; Cotlet does not store your password and you need no Little Hotelier API key. About the official Little Hotelier API: Little Hotelier has no API for its own customers (checked 11 Oct 2026). SiteMinder APIs need a partnership agreement with SiteMinder's Ecosystem team and are listed for PMS, channel, app and booking-engine vendors, so a property cannot get a key to read its reservations or change rates from a script. Setup and FAQ: https://cotlet.dev/integrations/little-hotelier-api-mcp-server

    Related MCP Servers