Infra MCP — Operações de VPS pelo Claude
odanree/infra-mcp
Gerencie Docker, Caddy e CI/CD remotos pelo Claude com confirmação e auditoria
Ver no GitHubMCP server que expõe ferramentas de leitura e escrita para gerenciar Docker, Caddy e GitHub Actions em uma VPS remota via SSH. Implementa confirmação explícita, allowlist de serviços e respostas auditáveis, permitindo que Claude execute operações de infraestrutura com segurança.
Instalação
npx convez-ai odanree/infra-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Verificar status e logs de containers Docker remotamente
- Reiniciar serviços com confirmação explícita para evitar acidentes
- Consultar histórico de deploys via GitHub Actions
- Monitorar espaço em disco e recursos antes de rebuilds
- Recarregar configuração Caddy sem downtime manual
Veredito

Solução sólida e bem-pensada para automação de ops com Claude: três camadas de segurança (allowlist, confirmação, tipagem), respostas auditáveis e timeouts limitados. Ideal para equipes que querem delegar operações de infraestrutura a IA sem risco de acidentes em produção.
README
A tradução para o português deste README ainda está na fila.
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: trueparameter so the model can't trip into a production bounce by accident. - Service allowlist. Write tools cross-check against
INFRA_ALLOWED_SERVICESfrom.env. Anything not listed is rejected even withconfirm=true. Editing the allowlist is a deliberate human action. - No shell injection. Tool inputs are typed (
tail: int,since: strvalidated against a\d+[smhd]shape,grepstrings 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_forand aConnectTimeout. 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_logsLangfuse 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