Caddy MCP Server

@yawlabs/caddy-mcp

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.

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

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/, /reverseproxy/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 caddymetrics with filter: "gogoroutines" or "gomemstats", 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 — caddyconfigset defaults to idempotent overwrite (PATCH), not append (POST). Calling twice doesn't duplicate your route.
• Defensive parsing — caddylistroutes 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 CADDYADMINURL 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 CADDYADMINURL.

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

Shortened. The full README is on GitHub.