agent ──stdio──▶ infra-mcp ──SSH──▶  VMs  (journald · log files)
                                  └──▶  DBs  (read-only PostgreSQL)

An agent can check service health, retrieve bounded logs, inspect DB state, and explore table schemas — without terminal access. Every remote operation is allowlist-gated and written to an append-only audit log.

Install

uv tool install infra-mcp
# or
pip install infra-mcp

Configure

Copy infra-mcp.yaml.example to ~/.infra-mcp/infra-mcp.yaml and edit it.

# Generate a starter config from ~/.ssh/config
infra-mcp generate-config -o ~/.infra-mcp/infra-mcp.yaml

# Create the read-only PostgreSQL role(s)
infra-mcp setup

# Check VM reachability
infra-mcp test

# Refresh discovered services, log dirs, and databases (updates config in place)
infra-mcp discover --in-place

Override the config path with --config or INFRA_MCP_CONFIG.

Run

infra-mcp run

Register as a stdio MCP server in your client (Claude Code, Cursor, …) with command infra-mcp run.

Updates

infra-mcp checks PyPI for a newer release once a day and, when one exists, prints a one-line hint to stderr telling you how to upgrade:

uv tool upgrade infra-mcp   # or: pip install --upgrade infra-mcp

The check runs in the background, never blocks startup, and never touches stdout. Print the installed version with infra-mcp --version. Disable the check entirely by setting INFRA_MCP_NO_UPDATE_CHECK=1.

Tools

VM & services

Databases

Meta

All output is bounded server-side (200 log lines, 100 DB rows, 200 tables/columns max). Truncation is always flagged with a -- TRUNCATED: marker. list_tables and describe_table cache results in memory (TTL: schema_cache_ttl_hours, default 24 h); pass refresh: true to force a live re-read.

Security model

• SSH commands and systemd services are checked against a per-VM allowlist before any network call.
• All DB queries run as a read-only role inside a READ ONLY transaction.
• Log file paths are resolved against a per-VM directory allowlist (.. traversal blocked).
• Every remote operation is appended to a local JSONL audit log.