Caddy MCP
You can inspect a local Caddy admin config and perform dry-run-by-default operations through the exposed MCP tools.
Read active JSON config, optionally below
/config/{path}.Summarize host matchers and
reverse_proxyupstreams from the active config.Validate Caddyfile text with
caddy validatewithout loading it.Convert Caddyfile text to JSON, previewing the command by default.
Replace active config with
POST /load(dry-run by default).Patch a config subpath with
PATCH /config/{path}(dry-run by default).Stop Caddy with
POST /stop(dry-run by default).
Provides tools for inspecting and safely operating a local Caddy admin API, including reading active JSON config, inventorying reverse-proxy upstreams, checking upstream health, validating/adapting Caddyfile text with the local caddy binary, and previewing or applying config loads, patches, and stop operations with dry-run defaults.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Caddy MCP show the current active config"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Caddy MCP
MCP server for safely inspecting and operating a local Caddy admin API. Built for homelab and personal-infra workflows where an AI assistant should be able to inspect active routes, validate Caddyfile snippets, and preview admin-API mutations before applying them.
Features
FastMCP stdio and SSE transports.
Safe default Caddy admin URL:
http://127.0.0.1:2019.Read-only tools for active config and reverse-proxy upstream inventory.
Caddyfile validation/adaptation helpers using the local
caddybinary.Mutating tools default to
dry_run=true.Redacted admin API errors.
Optional
CADDY_READ_ONLYmode (mutating tools not registered) andMCP_BEARER_TOKENfor SSE.Installable package layout, Dockerfile, Compose sidecar, CI, tests, and client examples.
Related MCP server: runn-mcp
Tools
Tool | Purpose | Mutates |
| Read active JSON config, optionally below | no |
| Summarize host matchers and | no |
| Live upstream status ( | no |
| Validate Caddyfile text with | no |
| Convert Caddyfile text to JSON; dry-run preview by default | no |
| Replace active config with | yes, unless dry-run |
| Patch one config path with | yes, unless dry-run |
| Stop Caddy with | yes, unless dry-run |
Configuration
Variable | Default | Effect |
|
| Caddy admin API base URL (http or https) |
| unset |
|
|
|
|
|
| SSE bind address |
| unset | SSE only: require |
validate_caddyfile_text and adapt_caddyfile_text(dry_run=false) shell out to a caddy binary on PATH; if it is missing they return an error result instead of raising.
Quick start
git clone https://github.com/euisuh/caddy-mcp.git
cd caddy-mcp
python -m venv .venv
. .venv/bin/activate
pip install -e .
CADDY_ADMIN_URL=http://127.0.0.1:2019 caddy-mcpFor SSE sidecar mode:
MCP_TRANSPORT=sse MCP_HOST=127.0.0.1 MCP_PORT=8000 caddy-mcpClient configuration
Claude Code (stdio):
claude mcp add caddy --env CADDY_ADMIN_URL=http://127.0.0.1:2019 -- caddy-mcpClaude Desktop (claude_desktop_config.json), using the caddy-mcp script from a virtualenv where the package is installed:
{
"mcpServers": {
"caddy": {
"command": "/path/to/caddy-mcp/.venv/bin/caddy-mcp",
"env": { "CADDY_ADMIN_URL": "http://127.0.0.1:2019", "CADDY_READ_ONLY": "1" }
}
}
}Drop CADDY_READ_ONLY to expose the dry-run-by-default mutating tools. More in examples/.
Docker sidecar
docker compose up --buildThe Compose file binds the MCP port to localhost and points at host Caddy's admin API via host.docker.internal:2019.
Safety model
Caddy's admin API is powerful. Keep it bound to loopback or an internal network.
This server does not expose credentials and does not persist tokens.
Mutating tools default to dry-run and return the exact method/path/value preview.
Set
CADDY_READ_ONLY=1to remove the mutating tools entirely.The SSE transport has no auth unless
MCP_BEARER_TOKENis set; the Compose file passes it through.Use
load_configandpatch_configonly after validating/adapting configs.stop_caddyexists for completeness but also defaults to dry-run.
Development
pip install -e . -r requirements-dev.txt
ruff check .
pytest -q
python -m build --sdist --wheel
twine check dist/*Live smoke against a local Caddy
CADDY_ADMIN_URL=http://127.0.0.1:2019 python - <<'PY'
import asyncio
from fastmcp import Client
from caddy_mcp.server import build_server
async def main():
async with Client(build_server()) as client:
print([tool.name for tool in await client.list_tools()])
print((await client.call_tool('list_reverse_proxy_upstreams', {})).data)
print((await client.call_tool('get_upstream_health', {})).data)
asyncio.run(main())
PYLicense
MIT
Available Tools
7 toolsadapt_caddyfile_textB
Convert Caddyfile text to JSON. Defaults to dry_run command preview.
Inputs: caddyfile (required), dry_run. Returns: object
get_configA
Read Caddy's active JSON config, optionally below /config/{path}.
Inputs: path.
list_reverse_proxy_upstreamsA
Summarize host matchers and reverse_proxy upstreams from the active config.
Inputs: no named parameters. Returns: result
load_configB
Replace Caddy's active config via POST /load. Defaults to dry_run.
Inputs: config (required), dry_run.
patch_configA
Patch a config subpath via PATCH /config/{path}. Defaults to dry_run.
Inputs: path (required), value (required), dry_run.
stop_caddyA
Stop the Caddy process via POST /stop. Defaults to dry_run.
Inputs: dry_run.
validate_caddyfile_textA
Run caddy validate against Caddyfile text without loading it.
Inputs: caddyfile (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct config operation: get_config reads the full config, list_reverse_proxy_upstreams extracts a specific view, validate_caddyfile_text and adapt_caddyfile_text are clearly different (validation vs. conversion), and load_config, patch_config, and stop_caddy each handle a unique mutation. The descriptions clearly separate the purposes, leaving no ambiguity.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., get_config, validate_caddyfile_text, patch_config). The verbs precisely indicate the action and the nouns specify the target, making the naming predictable and uniform.
Seven tools is a well-scoped set for a Caddy management server, covering reads, transformations, and mutations without bloat or unnecessary redundancy. Each tool earns its place in the collection.
The tool surface covers the core config lifecycle: read, validate, adapt, load, patch, and stop. Minor gaps exist, such as no explicit start or status command, but these are reasonable workarounds or may be handled externally, so the surface is largely complete.
Maintenance
Related MCP Connectors
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
Ovanek MCP: Model Context Protocol server for Ovanek platform tools; writes are dry-run by default.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Related MCP Servers
- AlicenseDqualityBmaintenanceMCP server for Porkbun domains and DNS, enabling read-only and mutating operations with safety features like dry-run and write mode toggle.40115 npm3MIT
- AlicenseBqualityNot gradedmaintenanceA generic MCP server that wraps the Runn REST API v1 (read + write) with ID-based tools and dry-run safety for write operations.32MIT
- AlicenseBqualityDmaintenanceLocal MCP server for inspecting and managing an allowlisted Discord server via Discord's REST API, with safety modes, idempotent JSON blueprints, and destructive-operation safeguards.271MIT
- AlicenseNot gradedqualityDmaintenanceRead-only MCP server to inspect allowlisted Docker containers, systemd services, JSONL logs, and HTTP health endpoints without arbitrary shell access.MIT