vllm-ops-mcp

Purpose

vllm-ops-mcp is a read-only ops/health-check MCP server for local vLLM instances managed by systemd inside WSL2. It is intended to provide health-check capabilities to operators and to other bots/tools that depend on that vLLM instance, and does not itself manage container lifecycle—it assumes vLLM is already running in WSL2 as a bare-metal systemd unit, not running in Docker/Podman.

Main capabilities

In this version, all tools are read-only and require no additional gating except for the throughput cap. The health signals provided by the server all come from real HTTP requests to the OpenAI-compatible API (using urllib.request, not socket/connect checks). This is deliberate: listener-based checks such as Get-NetTCPConnection will completely miss ports forwarded by WSL2 mirrored networking, and a genuinely healthy 127.0.0.1:8000 may be invisible to a listener probe run from the Windows host. The server generalizes this lesson into two tiers: liveness and real generation.

The specific capabilities involve:

• Health-check tiers: check_health(deep=True) and test_completion make real inference calls.
• GPU/VRAM status: get_gpu_status calls nvidia-smi to obtain GPU and VRAM information.
• systemd service status: get_service_status returns systemctl's raw ActiveEnterTimestamp string (already labeled with a time zone, such as MDT), rather than computing uptime server-side—this is a deliberate clock-discipline requirement; if a duration is needed, explicit time-zone conversion should be done on the caller side.
• Runtime serve parameter introspection: get_serve_config reads /proc/<pid>/cmdline, and across three sources (live_process, exec_script, local_config_mirror) uniformly replaces parameter values matching known sensitive patterns (token, key, secret, password, passwd, credential, see config.SENSITIVE_ARGV_FLAG_PATTERNS) with [REDACTED], while keeping parameter names visible for diagnostics.

The server invokes systemctl via wsl -d, executes nvidia-smi, and reads /proc/<pid>/cmdline. All six tools are read-only—it will not start, stop, restart, or kill any process; unit names/distribution names come from server-side configuration rather than caller input, and the only caller-adjacent path that reaches a shell string (the unit name in systemctl show) is wrapped with shlex.quote.

Usage

This server is registered in ~/.claude.json under the name vllm-ops-mcp (stdio, with its own .venv, and no environment variable overrides needed for this operator's default setup).

Regarding rate limiting: check_health(deep=True) and test_completion make real inference calls to the shared GPU server, with a default rate limit of 20 per minute, adjustable via VLLM_OPS_MCP_DEEP_RATE_LIMIT_PER_MIN. The reason for rate limiting is that this vLLM instance is shared infrastructure that other bots/tools rely on, and frequent requests from callers could starve or slow down other consumers, even if each individual call looks like a "read-only" operation.

WSL2-related configuration: the live-process paths of get_service_status and get_serve_config by default assume that the server process is running on the Windows host and enters WSL2 via wsl -d <distro>. If the server process itself runs natively inside WSL2/Linux, set VLLM_OPS_MCP_RUNS_IN_WSL=1 (using native systemctl / cat, with no need for wsl -d indirection). Both paths have unit tests, but only the Windows-host path has been tested in this operator's real environment.

CI (.github/workflows/ci.yml) runs the test suite on ubuntu-latest on every push/PR (unit tests mock HTTP/subprocess and do not require a live server/GPU/WSL); if Tests badges and suite actual reports being inconsistent will cause the build to fail (see scripts/check_readme_counts.py).

Applicable scenarios

Applicable to operators who deploy vLLM locally via WSL2 + systemd, for:

• Distinguishing "the port is alive" from "real inference is available", avoiding the blind spots of listener probing;
• Viewing GPU/VRAM usage (note the limitations below);
• Viewing systemd unit status;
• Performing read-only introspection of the serve parameters of a running vLLM process.

Limitations

• Designed only for scenarios managed by WSL2/systemd and that are bare-metal systemd units; it is not a container lifecycle manager.
• This version has no write/change capability whatsoever, nor is there any environment variable that can enable it: restart_service is not yet implemented in this codebase (it is a v2 idea).
• Under this operator's WSL2 GPU passthrough configuration, per-process VRAM attribution is unreliable: one real nvidia-smi smoke test returned an empty process list, but gpus[0].memory_used_mib from the same call correctly showed that the process was using 13.7GB. This is a known limitation of nvidia-smi --query-compute-apps under some WSL2/passthrough configurations; the tool will faithfully report an empty result (ok: true, processes: []), and will not fabricate attribution. Do not rely on processes for root-cause analysis of VRAM overcommit; gpus[].memory_used_mib is the reliable signal.
• It does not calculate service uptime: get_service_status returns the raw ActiveEnterTimestamp string.
• The exec-script fallback path of get_serve_config is best-effort shell text parsing (handling \ line continuations and basic quoting), not an exact argv array; when the unit is in a running state, always prefer the live-process path (the kernel's exact argv, null-separated).
• The live-process path of get_serve_config reads /proc/<pid>/cmdline, and if secrets were historically passed via CLI flags it may contain secrets (in this operator's actual setup there are none — the model path and flags are all non-secret; authentication, if any, is injected by the environment inside the exec script rather than passed as argv flags). The defensive measure is to perform [REDACTED] replacement on the values corresponding to known sensitive flag names.
• WSL2-specific by default, but the switching seam is explicit (see VLLM_OPS_MCP_RUNS_IN_WSL).
• Single vLLM instance, single GPU: there is no multi-instance/multi-GPU aggregation; get_gpu_status returns all GPUs enumerated by nvidia-smi --query-gpu, rather than being limited to "the GPU that vLLM is using".
• Whether commercial support is available: maintained by Jaimen Bell; for production-grade MCP integration, custom servers, or agent reliability work, see jaimenbell.dev. Details on whether paid/commercial services are available have not yet been provided.