Caddy MCP

Requirements

• Node.js 20+
• Caddy 2.x with admin API enabled (default: localhost:2019)

Atomic deploy

> "Replace the whole config with this Caddyfile"
→ caddy_adapt({ config: "..." })  # validate first
→ caddy_load({ config: adaptedJson })  # apply atomically

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"

Examples

Configuration

Alternate MCP clients:

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

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), append (POST), insert (PUT, for array positions).
• caddy_config_delete — Delete config at a path. Requires confirm=true (deleting a parent path also removes every descendant).
• caddy_config_by_id — Get/set/delete config by @id tag — much easier than navigating deep paths. The delete action requires confirm=true.
• caddy_load — Replace the entire config atomically. 60-second timeout for cert provisioning. Auto-snapshots the prior config.
• caddy_revert — Manage config snapshots for rollback. Actions: list, save, apply (confirm-gated). In-memory, last 10.

TLS & config conversion (2)

• caddy_tls — Check or set TLS settings: ACME email, ACME CA URL. PATCH first; on a fresh install, POSTs a minimal config. On an existing config it deep-merges into the issuer path and PUTs the result back, preserving siblings (custom certs, on_demand, additional policies). Refuses with a shape-specific error if the existing structure is unexpected — never clobbers.
• caddy_adapt — Convert a config in any registered adapter format to Caddy JSON without applying it. caddyfile (built-in, default) plus any adapter module compiled into your Caddy binary — e.g., nginx (caddy-nginx-adapter), yaml (caddy-yaml). Great for previewing or porting from existing configs.

Troubleshooting

"Cannot connect to Caddy admin API"

• Make sure Caddy is running. caddy run or systemctl status caddy.
• Check the admin endpoint. Default is http://localhost:2019. If Caddy is in Docker, use the container hostname.
• Set CADDY_ADMIN_URL in your MCP config env to match.

"HTTP 412 Precondition Failed"

• Someone (or something) changed the config between your read and your write.
• The cached ETag has been invalidated. Re-read the config and retry.

"HTTP 403" on /load or /config writes

• You have admin.listen or admin.origins restrictions set in your Caddy config, or you're missing an Authorization header.
• Set CADDY_API_TOKEN in your MCP config env if Caddy expects a Bearer token.

Windows: MCP server doesn't start

• Use the cmd /c npx ... pattern from the Quick start section. Node 20+ can't spawn .cmd files directly.