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 caddy binary.

• Mutating tools default to dry_run=true.

• Redacted admin API errors.

• Installable package layout, Dockerfile, Compose sidecar, CI, tests, and client examples.

Related MCP server: MCP Manager

Tools

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-mcp

For SSE sidecar mode:

MCP_TRANSPORT=sse MCP_HOST=127.0.0.1 MCP_PORT=8000 caddy-mcp

Docker sidecar

docker compose up --build

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

• Use load_config and patch_config only after validating/adapting configs.

• stop_caddy exists 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)

asyncio.run(main())
PY

License

MIT