infra-mcp 0.1.3

Local stdio MCP server for read-only diagnosis of on-prem Linux VMs and PostgreSQL databases

infra-mcp

Read-only MCP access to on-prem Linux VMs and PostgreSQL databases over SSH.

 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

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