Caddy MCP Server

@yawlabs/caddy-mcp

One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.

Manage Caddy web servers from Claude Code, Cursor, and any MCP client. 18 tools + 4 resources covering every endpoint in Caddy's admin API reference — config, routes, reverse proxies, TLS, PKI, metrics, snapshots.

Built and maintained by Yaw Labs.

Why this one?

Other Caddy MCP servers wrap half the admin API and silently swallow errors. This one doesn't.

• Complete admin API coverage — every endpoint in Caddy's admin API reference: /load, /config/*, /id/*, /stop, /adapt, /pki/ca/*, /reverse_proxy/upstreams, /metrics. No placeholder tools that 404. Caddy's Go runtime debug endpoints (/debug/pprof/*, /debug/vars) are deliberately not wrapped — for leak trends use caddy_metrics with filter: "go_goroutines" or "go_memstats", which come from the same admin registry; for stack dumps, CPU profiles and traces, curl the admin endpoint directly (Caddy profiling docs).
• Safe concurrent writes — uses ETags (If-Match) so your changes never silently overwrite someone else's. Surfaces HTTP 412 Precondition Failed as a clear message, not a cryptic error.
• Safe-by-default mutations — caddy_config_set defaults to idempotent overwrite (PATCH), not append (POST). Calling twice doesn't duplicate your route. A write to the config root — which replaces the *entire* config, admin endpoint included — is refused without confirm=true and snapshotted first, like caddy_load.
• Defensive parsing — caddy_list_routes never crashes on malformed config, even if routes are null, handlers are strings, or matchers are non-arrays. Regression-tested.
• No leaked credentials in errors — if CADDY_ADMIN_URL contains a token in the path/query, the connect-failed message shows only the origin.
• Fallback error surfacing — when a TLS write PATCH fails and the PUT fallback also fails, both error bodies are returned so you know what actually went wrong.
• Tool annotations — every tool declares readOnlyHint, destructiveHint, and idempotentHint, so MCP clients can skip confirmations for safe ops.
• Instant startup — ships as a single bundle with two runtime deps (the MCP SDK + Zod). No 5-minute node_modules install.
• Input hardening — adapter names, @id values, server names, and CA ids are all regex-validated with length caps. Blocks CRLF header injection and ReDoS.

Quick start

1. Enable the Caddy admin API

Caddy ships with the admin API enabled on localhost:2019 by default. If you're running Caddy in Docker or on a remote host, expose it via CADDY_ADMIN_URL.

2. Create `.mcp.json` in your project root

macOS / Linux / WSL:

{

"mcpServers": { "caddy": { "command": "npx", "args": ["-y", "@yawlabs/caddy-mcp@latest"] } } }

Windows:

{

"mcpServers": { "caddy": { "command": "cmd", "args": ["/c", "npx", "-y", "@yawlabs/caddy-mcp@latest"] } } }

Why the extra step on Windows? Since Node 20, child_process.spawn cannot directly execute .cmd files (that's what npx is on Windows). Wrapping with cmd /c is the standard workaround. This file is safe to commit — it contains no secrets.

3. Restart and approve

Restart Claude Code (or your MCP client) and approve the Caddy MCP server when prompted.

That's it. Now ask your AI assistant:

"Proxy api.local to localhost:3000"

"What routes are configured on srv0?"

"Show me the Prometheus metrics"

Configuration

Unix socket admin endpoints:

Caddy's recommended hardening is to move the admin API off a loopback port and onto a unix socket, where access is governed by filesystem permissions:

{

admin unix//var/run/caddy-admin.sock }

Point CADDY_ADMIN_URL at the same path (unix:///var/run/caddy-admin.sock) and requests are sent over the socket instead of TCP. The process running caddy-mcp needs read/write permission on the socket file. Leave CADDY_API_TOKEN unset here unless an authenticating proxy actually listens on that socket: over a unix path caddy-mcp is usually talking to Caddy's own socket, where the token does nothing — and, before Caddy 2.11.3, is logged in clear.

Runtime (oam or Node):

The caddy-mcp command prefers oam when it finds a usable one and otherwise runs on Node. It never serves on an oam older than 0.19.1.

An outdated oam is fixed with oam self-update. Under Yaw MCP, which runs servers on oam by default, yaw-mcp set runtime=node switches this server to Node.

Alternate MCP clients:

Use the same JSON block shown above in any of these.

Tools

Config management (6)

• caddy_config_get — Read config at any JSON path (or the full config).
• caddy_config_set — Write config at a path. Modes: overwrite (PATCH, default, idempotent; the key must exist, and the whole subtree at the path is replaced), append (POST: appends to an array, but replaces an existing non-array key and cannot create missing parents), insert (PUT: inserts at an array position, or strictly creates a key along with any missing parents and fails with 409 if it exists — the way to create a server or app, even on an instance with no config). append at a path ending in /... (e.g. apps/http/servers/srv0/routes/...) with an array value appends every element in one request — all or nothing, one reload; without the /..., an array value is added as a single element and Caddy rejects the load for typed arrays like routes or listen. A path that addresses the config root (`