vllm-ops-mcp

Read-only ops/health MCP server for a local, WSL2/systemd-managed vLLM server -- liveness vs. real-completion health tiers, GPU/VRAM status, systemd service status, and live serve-flag introspection. Built to the same standard as mcp-factory and desktop-mcp, and other local tooling in this operator's portfolio: own pyproject, own fastmcp server, honest README, real test suite, no product code before a spec was confirmed.

This is not a container-lifecycle manager. It assumes vLLM already runs as a bare-metal systemd unit inside WSL2 (this operator's actual setup -- see vllm-autostart), not inside Docker/Podman.

Quickstart

// ~/.claude.json (or any MCP-host stdio client config)
{
  "mcpServers": {
    "vllm-ops-mcp": {
      "type": "stdio",
      "command": "C:\\Users\\<you>\\projects\\vllm-ops-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\<you>\\projects\\vllm-ops-mcp\\run_server.py"]
    }
  }
}

Tools (Phase 1 -- all read-only, no gating required beyond a throughput cap)

Future extension: restart_service (Phase 2, not built)

Deliberately not implemented in this release. Per the spec: vLLM is shared infra other bots/tools depend on (options-bot, qwen_cli.py callers, DeerFlow fallback), so a restart tool needs its own gating design (off by default, VLLM_OPS_MCP_ENABLE_RESTART=1, refuse to touch a healthy instance unless force=True, rate-capped) before it ships -- not retrofitted onto a read-only MVP. Tracked as a v2 idea, not a current capability. If built, it should wrap run-vllm.cmd's exact recipe (systemctl start vllm only, never blind stop/restart) rather than reinvent it.

The differentiator: probe HTTP, not the listener

Every health signal in this server comes from an actual HTTP request to the OpenAI-compatible API (urllib.request, not a socket/connect check). This is deliberate, not incidental: Get-NetTCPConnection and other listener-based checks miss WSL2-mirrored-networking-relayed ports entirely -- a genuinely healthy 127.0.0.1:8000 can be invisible to a listener probe run from the Windows host. check-vllm.cmd already embodies this lesson; this server generalizes it into two tiers (liveness vs. real generation) that nothing else in this operator's fleet exposes as MCP tools.

Security

Read this before you register vllm-ops-mcp. Honesty about blast radius is the point.

• This server shells out to nvidia-smi, systemctl (via wsl -d), and reads /proc/<pid>/cmdline. All six tools are read-only -- nothing here starts, stops, restarts, or kills a process, and no tool accepts an argument that gets passed to a shell unescaped (unit/distro names come from server-side config, not caller input; shlex.quote wraps the one caller-adjacent path that does reach a shell string, the unit name in systemctl show).
• check_health(deep=True) and test_completion fire a real inference call against a shared GPU server. Rate-limited (default 20 calls/min, VLLM_OPS_MCP_DEEP_RATE_LIMIT_PER_MIN) specifically because this vLLM instance is shared infra other bots/tools depend on -- a caller hammering this MCP could starve or slow other consumers even though every call individually looks "read-only."
• get_serve_config's live-process path reads /proc/<pid>/cmdline, which can include secrets if any were ever passed as CLI flags (none are, in this operator's actual setup -- the model path and flags are all non-secret; auth, if any, is environment-injected inside the exec script, not passed as an argv flag). Defense-in-depth: any argv entry whose preceding flag name matches a known-sensitive pattern (token, key, secret, password, passwd, credential -- config. SENSITIVE_ARGV_FLAG_PATTERNS) has its value redacted to [REDACTED] before being returned, in both the structured argv/flags fields and raw_text; the flag name itself is left visible so the shape is still diagnosable. This applies across all three sources (live_process, exec_script, local_config_mirror).
• No tool has any write/mutate capability in this release. There is no env var that turns one on -- restart_service doesn't exist in this codebase yet (see Future extension above), so there's nothing to accidentally enable.

Honest-capabilities table