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

Alternate MCP clients:

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

Tools

Config management (6)