Infra MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Infra MCP listing page.
infra-mcp
Read-only MCP access to on-prem Linux VMs and PostgreSQL databases over SSH.
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
Configure
Copy infra-mcp.yaml.example to ~/.infra-mcp/infra-mcp.yaml and edit it.
Override the config path with --config or INFRA_MCP_CONFIG.
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:
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
| Tool | Purpose |
|---|---|
list_vms | All VMs with reachability and watched services |
get_infra_overview | Service states + DB health for one VM in a single call |
get_service_status | systemd state, uptime, last 5 log lines |
get_service_logs | Bounded journald logs, filtered by severity |
get_log_file | Last N lines of an allowed log file, optional grep |
Databases
| Tool | Purpose |
|---|---|
get_db_status | Connection counts, waiting locks, long-running query count |
query_db | Bounded caller-supplied SELECT |
list_tables | Tables in a database (schema + name), capped at 200 |
describe_table | Columns, types, primary key, foreign keys for one table |
Meta
| Tool | Purpose |
|---|---|
get_audit_log | Recent entries from the local audit log |
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 ONLYtransaction. - Log file paths are resolved against a per-VM directory allowlist (
..traversal blocked). - Every remote operation is appended to a local JSONL audit log.