MCP-Linx — MCP Server for Linux Infrastructure Diagnostics

Русская версия: README.ru.md.

Operator guide: docs/USER_GUIDE.md.

Status: Alpha (1.0.0). The plugin/tool API and configuration keys may change without a deprecation period. Not yet hardened for untrusted networks — see Security.

MCP-Linx is an MCP (Model Context Protocol) server for Linux infrastructure diagnostics. It provides tools for monitoring and diagnosing components: Linux host, Nginx, Docker, PostgreSQL, Redis, Systemd, Netdiag, Kubernetes, Prometheus, Loki.

Installation

# Create a virtual environment
python3.11 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

Related MCP server: linux-mcp

Running the Server

# Start MCP server (stdio mode)
python -m mcp_linx.main

# With MCP Inspector for debugging
npx @modelcontextprotocol/inspector python -m mcp_linx.main

Docker

Two deployment models with the same image:

• Model A (default, safe) — isolated container diagnosing remote hosts over SSH; postgres/redis/prometheus/loki/k8s over the network.

• Model B (host) — diagnosing the local host (Linux only): requires pid: host, network_mode: host and read-only mounts (see docker-compose.yml). Note: mounting docker.sock grants root-equivalent access to the Docker host.

# Build
docker build -t mcp-linx:latest .

# Run via compose (stdio; MCP clients: command=docker, args=["run","-i","--rm","mcp-linx:latest"])
docker compose run --rm mcp-linx

# Claude Desktop / MCP Inspector config
{
  "mcpServers": {
    "mcp-linx": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "/absolute/path/config:/app/config:ro", "mcp-linx:latest"]
    }
  }
}

Configuration

Main configuration file: config/settings.yaml

Environment variables: copy .env.example → .env for the five server settings only (names without a prefix). Plugin secrets must be supplied in the process environment, not added to .env: unknown dotenv keys cause a validation error. YAML expands ${VAR} / ${VAR:-default} from that environment; a missing variable without a default logs a warning and falls back to the entire unexpanded YAML. An empty environment value does not trigger the default. Expansion is textual (before YAML parsing), so values must remain valid in their YAML quoting context. See Environment and configuration for local and Docker setup, audit logging, and shutdown behavior.

plugins.enabled selects the active plugin set: only listed plugins are loaded, initialized, expose MCP tools, and participate in health checks. An empty or absent list means all discovered plugins. This is configuration of composition, not an access-control boundary (system tools and the MCP transport are unaffected).

security:
  readonly: true                    # Command validation only; not a Docker API write gate
  max_command_output_size: 10000
  max_log_lines: 500
  command_timeout_seconds: 30      # Default plugin command timeout (per-tool timeout wins)
  rate_limit_max_calls: 60         # Calls per tool per sliding window
  rate_limit_window_seconds: 60    # Window duration in seconds
  allowed_hosts: [localhost]      # Add names from hosts: to permit remote calls

# Multi-host: named remote targets for SSH-based diagnostics.
hosts: {}
# hosts:
#   web-1:
#     host: 10.130.0.23
#     port: 22
#     username: user
#     key_file: ~/.ssh/id_rsa
#     password: null                 # prefer env
#     host_key_policy: reject        # reject | warning | auto_add
#     known_hosts: null

plugins:
  enabled:
    - linux
    - nginx
    - docker
    - postgres
    - redis
    - systemd
    - netdiag
    - kubernetes
    - prometheus
    - loki

  postgres:
    host: "localhost"
    port: 5432
    password: "${POSTGRES_PASSWORD:-}" # From process environment; empty if absent
    # SSL/TLS modes: disable | allow | prefer | require | verify-ca | verify-full
    # verify-full is recommended for production (verifies CA + hostname)
    ssl_mode: "prefer"

  redis:
    host: "localhost"
    port: 6379
    password: "${REDIS_PASSWORD:-}" # From process environment; empty if absent

  nginx:
    log_path: "/var/log/nginx"
    stub_status_url: null # e.g. "http://127.0.0.1/nginx_status" — enables nginx_stub_status tool

  kubernetes:
    namespace: "default"

PostgreSQL SSL modes

plugins.postgres.ssl_mode is passed to libpq as sslmode (via psycopg2.connect), so values and semantics are libpq's:

prefer protects against passive sniffing only: it silently falls back to plaintext if TLS is unavailable. For production use verify-full (or at least verify-ca), make the CA available to the process (~/.postgresql/root.crt or a system trust store) and keep the configured host identical to the certificate name — otherwise the connection fails instead of downgrading. This server does not expose a CA path setting: use libpq's standard locations or PGSSLROOTCERT in the process environment.

SSH reliability: retries and tunnels

SSH command execution retries connection-level failures and reconnects (E1):

Only connection errors (SSHException, EOFError, OSError, ConnectionError) are retried. A non-zero command exit code is a normal result and is never retried, so read-only diagnostics stay idempotent and predictable.

PostgreSQL can be reached through an SSH server (E2), which helps when the database is only reachable from a bastion:

plugins:
  postgres:
    host: db.internal      # resolved on the SSH side
    port: 5432
    ssh:
      host: bastion        # SSH server to tunnel through
      username: ops
      key_file: ~/.ssh/id_rsa
      tunnel: true         # opt-in; requires ssh.host

The plugin opens an ephemeral 127.0.0.1:<port> listener and forwards it to db.internal:5432 through the SSH connection; the tunnel is closed on plugin destroy(). Redis does not need this: its tools run redis-cli on the remote host over SSH. Note that with a tunnel, TLS hostname verification (verify-full) applies to the tunnel address, so prefer verify-ca with a trusted CA.

End-to-end verification of a tunnel requires a real SSH server; it is not covered by CI (unit tests use a fake transport and cover the forwarding and wiring paths).

Jump host (bastion)

A named host can be reached through a bastion; the pool opens a direct-tcpip channel on the bastion and runs the SSH session to the target over it (E3):

hosts:
  db-1:
    host: 10.0.0.20          # target, resolved on the bastion
    username: ops
    key_file: ~/.ssh/id_rsa
    jump_host: bastion.example.com
    jump_port: 22            # default 22
    jump_username: jumper
    jump_key_file: ~/.ssh/jump
    # jump_password: use an env-substituted value, not a literal
    host_key_policy: reject  # applies to both the bastion and the target

The bastion is verified with the same host_key_policy / known_hosts as the target (so reject needs both keys in known_hosts). The bastion connection is reused with the target and closed together with it (drop / close_all).

PostgreSQL multi-target

Any pg_* tool accepts host: <target name>, where targets are described in the config (E4b). Each target gets its own connection, and — with ssh.tunnel: true — its own tunnel, so a primary and a replica behind a bastion can be diagnosed from one instance:

plugins:
  postgres:
    host: primary.db           # used when a tool is called without `host`
    port: 5432
    user: postgres
    password: "${POSTGRES_PASSWORD:-}"
    targets:
      replica:
        host: replica.db
      behind-bastion:          # reached through SSH (E2)
        host: internal.db
        ssh: {host: bastion, tunnel: true}

Unlisted fields are inherited from the plugin-level settings. An unknown target name returns an error listing the configured targets. Connections and tunnels are closed on plugin destroy().

Kubernetes multi-cluster

The Kubernetes plugin talks to one cluster per plugin instance, selected by plugins.kubernetes.kubeconfig / context. For several clusters run additional instances (separate CONFIG_PATH) or switch context — the k8s_* tools intentionally have no per-call cluster argument.

Tools

Linux Plugin (9 tools)

• linux_host_stats — Host statistics: CPU, memory, disk, load

• linux_processes — List of running processes

• linux_logs — Read system logs (journalctl, syslog)

• linux_network — Network interfaces, ports, connections

• linux_firewall — Firewall snapshot: nftables + policy routing (read-only)

• linux_disk — Disk and filesystem usage

• linux_memory — Detailed memory usage information

• linux_file_diagnostics — File path, permissions, immutable attributes, mount and service-user write check (read-only; user check requires plugins.linux.privileged_tools: true)

• linux_execute_command — Execute an arbitrary read-only command

Nginx Plugin (5 tools)

• nginx_status — Nginx service status and processes

• nginx_logs — Read error and access logs

• nginx_config — Nginx configuration check

• nginx_upstream — Upstream servers: config + real HTTP health check

• nginx_stub_status — stub_status metrics: active connections, requests

Docker Plugin (7 tools)

• docker_containers — List containers with filtering

• docker_logs — Container logs

• docker_stats — Container stats: CPU, memory, network

• docker_info — Full container or system info

• docker_events — Docker events

• docker_system_df — Docker disk usage

• docker_prune — Preview stopped containers (dry-run by default); deletion requires both execute=true and confirm=true

PostgreSQL Plugin (7 tools)

• pg_connections — Active connections

• pg_locks — Locks and blocked queries

• pg_slow_queries — Slow queries

• pg_activity — Full activity: current queries, states, waits

• pg_stats — Statistics: tables, indexes, databases

• pg_replication — Replication status (if configured)

• pg_tables — List of tables with sizes and stats

Redis Plugin (5 tools)

• redis_ping — Redis availability (PING)

• redis_info — INFO sections: memory, clients, stats, replication

• redis_clients — Client connections (CLIENT LIST)

• redis_slowlog — Slow log (SLOWLOG GET)

• redis_memory — Memory analysis: used, peak, fragmentation, evictions

Systemd Plugin (5 tools)

• service_status — Unit status (systemctl status/is-active)

• failed_units — Failed units list

• service_logs — Service logs via journalctl -u

• boot_analysis — Boot time analysis (systemd-analyze blame)

• service_ip_filter — Effective IP filter: unit files + eBPF/bpftool (ground truth)

Netdiag Plugin (6 tools)

• http_check — HTTP(S) check: status, timings, redirects

• tls_check — TLS certificate: expiry, chain, issuer

• dns_resolve — DNS resolution A/AAAA

• tcp_connect — TCP connect with timing

• tcp_connect_as — TCP probe as service user, per-uid filters (requires privileged_tools)

• tcpdump_probe — Short tcpdump slice (requires privileged_tools)

Kubernetes Plugin (6 tools)

• k8s_pods — Pods with phases and restarts

• k8s_events — Cluster/namespace events

• k8s_logs — Pod logs (kubectl logs)

• k8s_describe — Pod describe (conditions)

• k8s_top — Pod resources (kubectl top)

• k8s_deployments — Deployment status

Prometheus Plugin (4 tools)

• prom_query — Instant PromQL query

• prom_range — Range query over period

• prom_alerts — Firing/pending alerts

• prom_targets — Scrape targets up/down

Loki Plugin (3 tools)

• log_search — LogQL search over period

• log_labels — Label names/values

• log_tail — Recent lines by selector

System Tools

• system_health_check — Health check of all plugins

• get_diagnostic_context — Full diagnostic context

• get_summary — Brief system status summary

• diagnose_host — Parallel host snapshot: host stats, top processes, disk, memory, recent error logs (linux plugin). Optional host — a name from the hosts: registry.

• diagnose_web_service — Parallel web-service snapshot: nginx status, systemd unit status, recent nginx error logs, plus http_check when url is given. Optional service_name (default nginx) and host.

  kubeconfig: null # null = ~/.kube/config context: null # null = current-context

  prometheus:

Linux Plugin

• linux_host_stats

• linux_processes

• linux_logs

• linux_network

• linux_firewall — Firewall snapshot: nftables + policy routing (read-only)

• linux_disk

• linux_memory

• linux_execute_command

Nginx Plugin

• nginx_status

• nginx_logs

• nginx_config

• nginx_upstream

• nginx_stub_status

Docker Plugin

• docker_containers

• docker_logs

• docker_stats

• docker_info

• docker_events

• docker_system_df

• docker_prune

PostgreSQL Plugin

• pg_connections

• pg_locks

• pg_slow_queries

• pg_activity

• pg_stats

• pg_replication

• pg_tables

Redis Plugin

• redis_ping

• redis_info

• redis_clients

• redis_slowlog — Slow log (SLOWLOG GET)

• redis_memory

Systemd Plugin

• service_status

• failed_units

• service_logs

• boot_analysis

• service_ip_filter

Netdiag Plugin

• http_check

• tls_check

• dns_resolve

• tcp_connect

• tcp_connect_as

• tcpdump_probe

Kubernetes Plugin

• k8s_pods

• k8s_events

• k8s_logs

• k8s_describe

• k8s_top

• k8s_deployments

Prometheus Plugin

• prom_query

• prom_range

• prom_alerts

• prom_targets

Loki Plugin

• log_search

• log_labels

• log_tail

Architecture

mcp-linx/
├── src/mcp_linx/
│   ├── main.py               # MCP server entry point (FastMCP + AgentLoop)
│   ├── harness/              # Harness core: agent_loop, plugin_manager (auto-discovery),
│   │                         #   context (compaction library API)
│   ├── multihost.py          # HostRegistry — named remote hosts (`hosts:` config)
│   ├── context_aggregator.py # Cross-component correlations
│   ├── security.py           # SecurityGuard (command validation, readonly mode)
│   ├── types.py              # Status, ToolResult, ComponentState, Correlation
│   ├── adapters/
│   │   ├── base.py           # Base adapter (abstract) + LocalAdapter
│   │   ├── ssh.py            # SSH adapter (paramiko)
│   │   ├── ssh_pool.py       # SSHConnectionPool + RemoteHostAdapter (multi-host)
│   │   └── docker.py         # Docker API adapter
│   └── plugins/              # Auto-discovered plugins (10 total, 57 tools)
│       ├── base.py           # DiagnosticPlugin base class (+ `host` resolution)
│       ├── linux/            # 9 tools
│       ├── nginx/            # 5 tools
│       ├── docker/           # 7 tools
│       ├── postgres/         # 7 tools
│       ├── redis/            # 5 tools
│       ├── systemd/          # 5 tools
│       ├── netdiag/          # 6 tools
│       ├── kubernetes/       # 6 tools
│       ├── prometheus/       # 4 tools
│       └── loki/             # 3 tools
├── config/settings.yaml      # Server configuration
├── tests/                    # Unit + integration tests; see Testing below
├── REMOTE_TROUBLESHOOTING.md   # Remote/SSH roadmap
└── docs/                     # ARCHITECTURE.md, DEVELOPMENT.md, SKILLS.md,
                              #   INCIDENT_504.md, skills/

Key features:

• Harness ideology: diagnostic plugins are auto-discovered from src/mcp_linx/plugins/; agent loops are selectable via AGENT_LOOP and context compactors are provided as a library API. Sandboxes are not part of the server (see docs/HARNESS_ANALYSIS.md).

• Security: readonly mode blocks write commands (rm, mkfs, dd, fork bombs, etc.)

• Context Aggregator: detects cross-component correlations

• Adapters: Local subprocess, SSH (paramiko), Docker API

• Multi-host: named remote targets in hosts:; linux_*, nginx_* (except nginx_stub_status) and systemd_* accept a host argument — see REMOTE_TROUBLESHOOTING.md

Testing

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/unit/test_security.py -v
pytest tests/unit/test_new_plugins.py -v

Security

Rate limiting applies to plugin tool handlers only; the system tools (get_diagnostic_context, get_summary, system_health_check, diagnose_host, diagnose_web_service) are registered separately and are not rate limited. Note that diagnose_* invoke plugin tools directly, so their inner calls are neither rate limited nor audited individually. Rejected calls are not audited.

SecurityGuard provides:

• Read-only mode: Command validation blocks write commands (rm, write, mkfs, dd and others) for command-executing adapters and tools. Non-command write paths are also covered: docker_prune refuses to delete while readonly: true (the confirm gate is an additional, independent barrier).

• Dangerous command blocking: rm -rf /, mkfs, dd if=/dev/zero, fork bombs etc.

• Output size limiting: Truncates large command outputs

• Log line limiting: Maximum number of log lines returned

• Host validation: Linux, Nginx and Systemd validate an explicit host against security.allowed_hosts before resolving the adapter. These are registry names, not destination IPs; define them in hosts: and include them in the allowlist. An empty allowlist disables this restriction. This is not a universal network ACL for API clients or probe destinations.

• Input validation: MCP handlers accept a params dictionary; field checks are implemented by individual tools, not dedicated Pydantic schemas for every tool.

Context Aggregator

ContextAggregator analyzes states of all components and detects correlations:

• Docker + Nginx: If Docker containers are down, Nginx may have no upstreams

• PostgreSQL + Docker: If PostgreSQL is in a container and failing

• Linux + components: If Linux is in critical state, other components may fail

• OOM events: Linux OOM messages may explain container crashes

• Redis + PostgreSQL: Redis evictions while PG is slow — cache-miss cascade

• Linux + Kubernetes: Pods OOMKilled while host has memory pressure

• Netdiag + Nginx: TLS certificate issue while Nginx is failing

License

MIT is declared in package metadata. A standalone LICENSE file is still missing; license text and copyright attribution remain pending (TODO C1).