infra-mcp

MCP server that wraps Docker / Caddy / GitHub Actions ops on a remote VPS. Lets Claude take read-then-write-with-confirmation infra actions over SSH, with a service allowlist and audit-trail-friendly responses.

MCP · FastMCP · Claude Code · Claude Desktop · Docker Compose · Caddy · GitHub Actions · Pydantic v2 · httpx · pytest-asyncio

Tool	Read/Write	What it does
infra_status	R	docker compose ps parsed into one row per container
infra_logs	R	tail logs from one service with --since + plain-text grep
infra_disk	R	df -h / + docker system df for "is there room to rebuild?"
infra_deploys	R	last N GitHub Actions runs per configured repo
service_url	R	resolves <svc>.<INFRA_PUBLIC_DOMAIN> and probes HTTP status
infra_restart	W	restart a compose service (confirm=true + allowlisted)
caddy_reload	W	reload Caddy in-place (confirm=true)

Why this exists

I spent a full afternoon on a single deploy SSH'ing to a VPS, running docker compose logs ..., scrolling, restarting things, re-SSH'ing. Every one of those steps is a tool call this server exposes. Now: "what's broken on <service> in the last 20 minutes?" in Claude Code — done.

This is also the canonical interview answer for "build us an MCP server for internal team operations": an ops surface wrapped as MCP, with three safety layers (allowlist, confirm gate, structured responses).

Safety model

• Read vs write split. Status/logs/disk/deploys/url are always callable. Restart/reload require an explicit confirm: true parameter so the model can't trip into a production bounce by accident.
• Service allowlist. Write tools cross-check against INFRA_ALLOWED_SERVICES from .env. Anything not listed is rejected even with confirm=true. Editing the allowlist is a deliberate human action.
• No shell injection. Tool inputs are typed (tail: int, since: str validated against a \d+[smhd] shape, grep strings quoted with single-quote escaping). Commands are assembled from typed params on the server, never from raw MCP-client strings.
• Bounded outputs. Logs are clamped to INFRA_MAX_LOG_LINES (500 by default) so a tool call can't dump 50 MB into the model context.
• Hard timeouts. Every SSH invocation runs under asyncio.wait_for and a ConnectTimeout. A wedged container or unreachable box returns an error, not a hang.

Install

git clone https://github.com/odanree/infra-mcp
cd infra-mcp
python -m venv .venv
.venv/Scripts/activate           # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

cp .env.example .env             # edit ssh host + allowlist + (optional) GH token

Requires the ssh binary on PATH and SSH-key auth already configured for the target host (your normal ~/.ssh/config works).

Register with Claude Code (user-scope)

claude mcp add infra -s user -- "/abs/path/to/infra-mcp/.venv/Scripts/python.exe" -m server.main
claude mcp list                  # confirms "infra" connected

Restart Claude Code, then try:

"Show me the infra status. Anything not running?"

"Tail logs for the api service since 10m and grep for 'Error'."

"Restart the api service — confirm=true."

Tests

pytest
# SSH is patched at the run() boundary — no network in the test suite.

Roadmap

• infra_logs Langfuse export: when a service has Langfuse-traced calls, return a list of recent trace IDs alongside log lines so you can jump straight from a 500 to the trace.
• service_url + cert expiry: when the HTTP probe succeeds, also surface days-until-cert-expiry from Caddy's storage.
• Per-tool audit-log file on the target so any write action has a permanent local record independent of Claude's chat log.

License

MIT