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\\jaime\\projects\\vllm-ops-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\jaime\\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

Limitations (read before relying on this)

• Per-process VRAM attribution is unreliable under this operator's actual WSL2 GPU-passthrough config. get_gpu_status's live smoke test (real nvidia-smi.exe against the real running vLLM process) returned an empty processes list even though the same call's gpus[0]. memory_used_mib correctly showed 13.7GB in use by that process. This is a documented nvidia-smi --query-compute-apps limitation under some WSL2/passthrough configurations, not a bug in this server's parsing -- the tool reports the empty result honestly (ok: true, processes: []) rather than fabricating attribution. Don't rely on processes for VRAM-overshoot root-causing on this setup; gpus[].memory_used_mib is the reliable signal.
• No computed service uptime. get_service_status returns the raw ActiveEnterTimestamp string from systemctl (already timezone-labeled, e.g. MDT) rather than computing an elapsed duration server-side -- deliberately, per this operator's own clock-discipline rule (never state an elapsed/ETA time from estimation; artifact timestamps are often UTC while local is UTC-6/-7). Compute the delta at the call site if you need it, with an explicit timezone conversion.
• get_serve_config's exec-script fallback is best-effort shell-text parsing, not an exact argv array -- it handles \ line continuations and basic quoting via shlex.split, but a sufficiently unusual exec script could parse incorrectly. The live-process path (/proc/<pid>/ cmdline) does not have this limitation (it's the kernel's exact argv, null-separated) and is always preferred when the unit is up.
• WSL2-specific by default, but the seam is explicit. get_service_status and get_serve_config's live-process path assume this server runs on the Windows host and shells into WSL2 via wsl -d <distro>. Set VLLM_OPS_MCP_RUNS_IN_WSL=1 if this server process itself runs inside WSL2/Linux natively (native systemctl/cat, no wsl -d hop) -- both paths are unit-tested (TestGetServiceStatus::test_uses_wsl_prefix_on_windows / test_no_wsl_prefix_when_native), but only the Windows-host path has been live-verified against this operator's actual setup.
• Single vLLM instance, single GPU, this operator's setup. No multi-instance/multi-GPU aggregation; get_gpu_status returns whatever nvidia-smi --query-gpu enumerates, which is every GPU visible to the process, not scoped to "the GPU vLLM is using" if more than one exists.
• No lifecycle control whatsoever in this release. See "Future extension" above -- this is intentional, not an oversight.

Env vars

Usage examples

// A tool call from the MCP host, illustrative -- not a shell command.
{"tool": "check_health", "arguments": {"deep": true}}
// -> {"ok": true, "status": "up", "tier": "deep", "model_id": "qwen3-14b",
//     "latency_ms": 32.0, "completion_s": 0.218, "error": ""}

{"tool": "get_serve_config", "arguments": {}}
// -> {"ok": true, "source": "live_process", "pid": 5645,
//     "flags": {"model": "Qwen/Qwen3-14B-AWQ", "served_model_name": "qwen3-14b",
//               "port": "8000", "max_model_len": "8192",
//               "gpu_memory_utilization": "0.72", "max_num_seqs": "8",
//               "enable_auto_tool_choice": true, "tool_call_parser": "qwen3_xml", ...}}

// rate limit exceeded (21st deep call within a minute):
{"tool": "test_completion", "arguments": {"prompt": "hi"}}
// -> {"ok": false, "error": {"type": "rate_limited", "group": "deep_inference",
//     "tool": "test_completion", "limit_per_min": 20, "retry_after_s": 4.87}}

Testing

CI (.github/workflows/ci.yml) runs this suite on every push/PR (ubuntu-latest -- the unit suite mocks HTTP/subprocess, no live server/GPU/WSL required) and fails the build if the Tests badge above drifts from what the suite actually reports -- see scripts/check_readme_counts.py.

# unit suite (mocked HTTP/subprocess, no live server/GPU/WSL required)
.venv\Scripts\python.exe -m pytest -q
# -> 95 passed, 7 skipped

# handshake check -- prints every registered tool name
.venv\Scripts\python.exe scripts\list_tools.py

# real-infra smokes (real vLLM completion, real nvidia-smi, real systemctl
# via WSL, real /proc/<pid>/cmdline read) -- read-only, safe to run anytime
# vLLM is up
VLLM_OPS_MCP_LIVE=1 .venv\Scripts\python.exe -m pytest -v -m live
# -> 7 passed (all live, against the actual running qwen3-14b instance)

Install

python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt

Registered in ~/.claude.json as vllm-ops-mcp (stdio, own .venv, no env overrides needed for this operator's default setup).

Commercial support

Maintained by Jaimen Bell. For production MCP integrations, custom servers, or agent-reliability work, see jaimenbell.dev or sponsor ongoing maintenance via GitHub Sponsors.

mcp-name: io.github.jaimenbell/vllm-ops-mcp