vllm-ops-mcp

vllm-ops-mcp

ローカルの、WSL2/systemd 管理下にある vLLM サーバー向けの読み取り専用オペレーション／ヘルス MCP サーバーです。生存確認と実際の生成を確認するヘルスチェックの段階、GPU／VRAM の状態、systemd サービスの状態、実行中の serve フラグのイントロスペクションに対応しています。mcp-factory や desktop-mcp、このオペレーターのポートフォリオにあるその他のローカルツールと同じ基準で構築されています。独自の pyproject、独自の fastmcp サーバー、誠実な README、実際のテストスイートを備え、仕様の確認前に製品コードを作成することはありません。

これはコンテナーのライフサイクル管理ツールではありません。vLLM が Docker／Podman 内ではなく、WSL2 内のベアメタルの systemd ユニットとしてすでに実行されていることを前提としています（このオペレーターの実際の構成については、vllm-autostart を参照してください）。

クイックスタート

// ~/.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"]
    }
  }
}

ツール（フェーズ 1 ― すべて読み取り専用で、必要な制限はスループット上限のみ）

ツール	実行する内容	実行できない内容
check_health(deep: bool = False)	deep=False：GET /v1/models による生存確認（llm_router.LocalLLM.is_healthy() と同じシグナル）。deep=True：さらに、最小限の実際の /v1/chat/completions 呼び出しを 1 回実行し（check-vllm.cmd の 2 段階プローブを再現）、サーバーが単にモデルがロード済みだと報告するだけでなく、実際に生成することを確認します。	劣化したサーバーを修復することはできません。実際の状態を報告するだけです。deep=True はレート制限されています（デフォルトは 20 回／分。以下を参照）。
list_models	/v1/models のパススルーです。	vLLM の API 自体が公開する以上の詳細情報はありません。
test_completion(prompt, max_tokens=16)	呼び出し元が指定したプロンプトを使い、手動の簡易確認用に実際の生成をオンデマンドで実行します。	レート制限されています（check_health(deep=True) と同じバケット）。先に生存確認が失敗した場合は実行を拒否します（そもそも待ち受けていないサーバーに生成を要求しても意味がありません）。max_tokens はサーバー側で 1024（config.MAX_TEST_COMPLETION_TOKENS）に制限され、プロンプトは 8000 文字（config.MAX_TEST_COMPLETION_PROMPT_CHARS）までです（上限を超えたプロンプトは切り詰めず、拒否します）。レート制限が抑えるのは呼び出しの頻度だけであり、1 回の呼び出しのコストではありません。
get_gpu_status	nvidia-smi ラッパーです。GPU ごとの VRAM 使用量／合計量と使用率に加え、--query-compute-apps によるプロセスごとの VRAM を返します。	このオペレーターの実際の WSL2 環境では、プロセスごとの VRAM の帰属情報は機能しません。vLLM プロセスが 13.7GB を保持している間も、ライブ検証で空であることを確認済みです（制限事項を参照）。processes は、信頼できる PID ごとの内訳ではなく、ベストエフォートで取得され、空であることも多い情報として扱ってください。
get_service_status	Windows ホストから wsl -d <distro> 経由で systemctl show <unit> -p ... を実行します（自由形式のテキスト解析ではなく、構造化されたプロパティ出力を使用）。このサーバー自体が WSL2／Linux 内で実行されている場合は、ネイティブの systemctl を使用します。ロード／アクティブ／サブ状態、再起動回数、メイン PID、最終アクティブ時刻を返します。	読み取り専用のため、ユニットを起動／停止／再起動することはできません。稼働時間の計算値はありません（意図的な仕様です。制限事項と時刻管理に関する注記を参照）。
get_serve_config	起動フラグを読み取り専用でイントロスペクションします。実行中のプロセスの実際の argv（systemd ユニットの MainPID の /proc/<pid>/cmdline。現在実行中の内容を示す実際の情報）を優先し、プロセスが起動していない場合に限り、静的な exec スクリプト（VLLM_OPS_MCP_SERVE_CONFIG_PATH 経由のローカルミラー、または WSL 側の exec スクリプトをライブで cat したもの）にフォールバックします。	vLLM は API 経由で独自の起動フラグを公開しないため、このツールがサーバー自体に問い合わせることはありません。常にシェルコマンドを実行します。exec スクリプトへのフォールバックでの解析は、シェルテキストのベストエフォート解析です（実行中の argv を使う方法より精度が低くなります）。

今後の拡張：restart_service（フェーズ 2、未実装）

このリリースでは意図的に実装していません。仕様にあるとおり、vLLM は他のボット／ツール（options-bot、qwen_cli.py の呼び出し元、DeerFlow のフォールバック）が依存する共有インフラです。そのため、再起動ツールをリリースするには、独自の制御設計（デフォルトでは無効、VLLM_OPS_MCP_ENABLE_RESTART=1、force=True でない限り正常なインスタンスには触れない、実行頻度を制限する）が必要です。読み取り専用の MVP に後付けするものではありません。v2 のアイデアとして記録されており、現時点の機能ではありません。実装する場合は、独自に作り直すのではなく、run-vllm.cmd の正確な手順（systemctl start vllm のみ。無条件の stop／restart は決して行わない）をラップするべきです。

差別化要素：リスナーではなく HTTP をプローブする

このサーバーのすべてのヘルスシグナルは、OpenAI 互換 API への実際の HTTP リクエスト（ソケット／接続チェックではなく urllib.request）から取得されます。これは偶然ではなく、意図的な設計です。Get-NetTCPConnection などのリスナーベースのチェックでは、WSL2 のミラーリングされたネットワーク経由で中継されるポートを完全に見落とします。実際には正常な 127.0.0.1:8000 が、Windows ホストから実行したリスナープローブでは見えないことがあります。check-vllm.cmd はすでにこの教訓を体現しており、このサーバーはそれを 2 つの層（ライブネスと実際の生成）に一般化しています。このオペレーターの環境では、ほかに MCP ツールとして提供されているものはありません。

セキュリティ

vllm-ops-mcp を登録する前に、これをお読みください。影響範囲について正直に説明することが重要です。

• このサーバーは nvidia-smi、systemctl（wsl -d 経由）をシェルから実行し、/proc/<pid>/cmdline を読み取ります。 6 つのツールはすべて読み取り専用です。プロセスを起動、停止、再起動、強制終了するものはなく、シェルでエスケープされずに渡される引数を受け取るツールもありません（ユニット名／ディストリビューション名は呼び出し元の入力ではなく、サーバー側の設定から取得します。呼び出し元の入力に関わる値のうち、シェル文字列に到達するものは systemctl show のユニット名だけで、shlex.quote によって囲まれます）。
• check_health(deep=True) と test_completion は、共有 GPU サーバーに対して実際の推論呼び出しを行います。 この vLLM インスタンスは他のボット／ツールが依存する共有インフラであるため、レート制限されています（デフォルトは 1 分あたり 20 回、VLLM_OPS_MCP_DEEP_RATE_LIMIT_PER_MIN）。この MCP の呼び出し元がリクエストを大量に送ると、個々の呼び出しが「読み取り専用」に見えても、ほかの利用者を圧迫したり、処理を遅らせたりする可能性があります。
• get_serve_config のライブプロセス経由の処理は /proc/<pid>/cmdline を読み取ります。 CLI フラグとしてシークレットが渡されていた場合、これに含まれる可能性があります（このオペレーターの実際の設定では、モデルパスもフラグもシークレットではありません。認証情報がある場合は、argv フラグとして渡されるのではなく、exec スクリプト内で環境変数として注入されます）。多層防御として、直前のフラグ名が既知の機密情報パターン（token、key、secret、password、passwd、credential。config. SENSITIVE_ARGV_FLAG_PATTERNS）に一致する argv エントリは、構造化された argv／flags フィールドと raw_text の両方で、値が [REDACTED] に置き換えられてから返されます。フラグ名は表示したままにし、構造を診断できるようにしています。この処理は 3 つのソース（live_process、exec_script、local_config_mirror）すべてに適用されます。
• このリリースでは、書き込み／変更機能を持つツールはありません。 それを有効にする環境変数もありません。restart_service はこのコードベースにまだ存在しないため（上記の「今後の拡張」を参照）、誤って有効にしてしまうこともありません。

正直な機能一覧

主張	実装	検証方法
ライブネスヘルス階層（/v1/models）	vllm_ops_mcp/probes.py::_probe_models、check_health	tests/test_probes.py::TestCheckHealthLiveness、ライブ：tests/test_live_smoke.py::test_live_check_health_liveness
詳細／実際の補完によるヘルス階層	vllm_ops_mcp/probes.py::_probe_completion、check_health(deep=True)	tests/test_probes.py::TestCheckHealthDeep、ライブ：test_live_check_health_deep
モデル一覧のパススルー	probes.py::list_models	tests/test_probes.py::TestListModels、ライブ：test_live_list_models
オンデマンドの補完サニティチェック	probes.py::test_completion	tests/test_probes.py::TestTestCompletion、ライブ：test_live_test_completion
nvidia-smi による GPU／VRAM の状態	probes.py::get_gpu_status	tests/test_probes.py::TestGetGpuStatus、ライブ：test_live_get_gpu_status
プロセスごとの VRAM 割り当て	probes.py::get_gpu_status（--query-compute-apps）	モックした空でない応答でユニットテスト済み。このオペレーターの実際の WSL2 環境では、ライブ検証により空の結果が返ることを確認済みです ― 詳細は「制限事項」を参照
構造化された systemctl show による systemd ユニットの状態	probes.py::get_service_status	tests/test_probes.py::TestGetServiceStatus、ライブ：test_live_get_service_status
/proc/<pid>/cmdline による実行中プロセスの起動フラグの調査	probes.py::get_serve_config、parse_launch_flags	tests/test_probes.py::TestGetServeConfig、TestParseLaunchFlags、ライブ：test_live_get_serve_config ― ライブ検証により、フラグ（--enable-auto-tool-choice --tool-call-parser qwen3_xml）を取得できることを確認しました。このフラグは、このリポジトリ独自の根拠仕様には記載されていなかったため、静的なドキュメントを信頼するよりも、ライブの argv を使う方法が優れていることを示しています
ユニット停止時の Exec スクリプトへのフォールバック	probes.py::get_serve_config、_parse_exec_script_text	tests/test_probes.py::TestGetServeConfig::test_falls_back_to_exec_script_when_service_down
ローカル設定ミラーによるオーバーライドパス	probes.py::get_serve_config + config.serve_config_override_path	tests/test_probes.py::TestGetServeConfig::test_uses_local_override_file、test_override_file_missing_reports_error
get_serve_config での機密フラグ値のマスキング	probes.py::redact_argv、redact_raw_text、config.SENSITIVE_ARGV_FLAG_PATTERNS	tests/test_probes.py::TestGetServeConfig::test_live_process_redacts_sensitive_flag_values、test_exec_script_raw_text_redacts_sensitive_flag_values、test_local_override_file_redacts_sensitive_flag_values
詳細推論のレート制限（共有インフラの保護）	config.py::TokenBucket、DeepRateLimiter、check_deep_rate_limit	tests/test_config.py::TestTokenBucket、TestDeepRateLimiter
WSL とネイティブ環境のシェル実行抽象化	probes.py::_shell_args、config.runs_in_wsl	tests/test_config.py::TestRunsInWsl、tests/test_probes.py::TestGetServiceStatus::test_uses_wsl_prefix_on_windows、test_no_wsl_prefix_when_native
6 つのツールすべてが登録済みで、Phase-2 のツールは存在しないこと	vllm_ops_mcp/server.py	tests/test_server.py

制限事項（このサーバーを利用する前にお読みください）

• このオペレーターの実際の WSL2 GPU パススルー設定では、プロセスごとの VRAM 使用量の帰属を正確に把握できません。 get_gpu_status のライブスモークテスト（実際に稼働している vLLM プロセスに対して実際の nvidia-smi.exe を実行）では、同じ呼び出しの gpus[0]. memory_used_mib がそのプロセスによる 13.7GB の使用を正しく示していたにもかかわらず、processes リストは空でした。これは一部の WSL2／パススルー設定における nvidia-smi --query-compute-apps の既知の制限であり、このサーバーの解析処理の不具合ではありません。このツールは帰属情報を捏造せず、空の結果（ok: true, processes: []）をそのまま報告します。この環境で VRAM 超過の原因を特定する際に processes を頼りにしないでください。信頼できる指標は gpus[].memory_used_mib です。
• サービス稼働時間は計算されません。 get_service_status は systemctl の生の ActiveEnterTimestamp 文字列（MDT のようにタイムゾーン表記を含む）を返します。サーバー側では経過時間を計算しません。これは、このオペレーター自身の時刻管理ルール（推定に基づく経過時間や到着予定時刻を決して示さないこと。アーティファクトのタイムスタンプは UTC で、ローカル時刻は UTC-6／-7 であることが多いため）に従った意図的な仕様です。必要な場合は、明示的にタイムゾーンを変換したうえで呼び出し元で差分を計算してください。
• get_serve_config の exec スクリプトへのフォールバックは、シェルテキストをベストエフォートで解析するものであり、正確な argv 配列ではありません。 \ による行継続と、shlex.split を使った基本的な引用符には対応していますが、十分に特殊な exec スクリプトは正しく解析できない可能性があります。ライブプロセスの経路（/proc/<pid>/ cmdline）にはこの制限がありません（カーネルが提供する、ヌル文字区切りの正確な argv です）。ユニットが稼働している場合は、常にこちらが優先されます。
• デフォルトでは WSL2 専用ですが、切り替え方法は明示されています。 get_service_status と get_serve_config のライブプロセス経路は、このサーバーが Windows ホスト上で稼働し、wsl -d <distro> を介して WSL2 でコマンドを実行することを前提としています。このサーバープロセス自体が WSL2／Linux 内でネイティブに稼働する場合は、VLLM_OPS_MCP_RUNS_IN_WSL=1 を設定してください（ネイティブの systemctl／cat を使用し、wsl -d による切り替えは行いません）。どちらの経路もユニットテスト済み（TestGetServiceStatus::test_uses_wsl_prefix_on_windows ／ test_no_wsl_prefix_when_native）ですが、このオペレーターの実際の環境でライブ検証済みなのは Windows ホスト経路のみです。
• このオペレーターの環境では、vLLM インスタンスは 1 つ、GPU も 1 基です。 複数インスタンスや複数 GPU の集約には対応していません。get_gpu_status は nvidia-smi --query-gpu が列挙する内容を返します。つまり、プロセスから見えるすべての GPU が対象であり、複数の GPU が存在する場合でも「vLLM が使用している GPU」だけに限定されるわけではありません。
• このリリースでは、ライフサイクル制御には一切対応していません。 上記の「今後の拡張」を参照してください。これは意図的な仕様であり、見落としではありません。

環境変数

変数	効果	デフォルト
VLLM_OPS_MCP_BASE_URL	OpenAI 互換のベース URL	http://127.0.0.1:8000/v1（localhost ではなく 127.0.0.1 を明示。qwen_cli.py の IPv6 によるハングの注意事項を参照）
VLLM_OPS_MCP_MODEL	completion ペイロードで使用する served-model-name	qwen3-14b
VLLM_OPS_MCP_WSL_DISTRO	vLLM をホストする WSL ディストリビューション	Ubuntu-22.04
VLLM_OPS_MCP_SERVICE_UNIT	systemd ユニット名	vllm
VLLM_OPS_MCP_EXEC_SCRIPT_PATH	serve exec スクリプトの WSL 側パス（フォールバック元）	~/vllm-systemd-exec.sh
VLLM_OPS_MCP_SERVE_CONFIG_PATH	exec スクリプトのローカルファイルミラー。設定すると、get_serve_config はフォールバック元として WSL でコマンドを実行する代わりに、ここから直接読み取ります	未設定
VLLM_OPS_MCP_NVIDIA_SMI_PATH	nvidia-smi バイナリーの上書き設定	nvidia-smi（Windows ホスト）／nvidia-smi.exe（ネイティブ WSL2）
VLLM_OPS_MCP_RUNS_IN_WSL	このサーバープロセス自体が WSL2／Linux 内で稼働する場合は 1 を設定（wsl -d による切り替えを省略）	sys.platform による自動検出
VLLM_OPS_MCP_DEEP_RATE_LIMIT_PER_MIN	check_health(deep=True) と test_completion の呼び出し回数／分の上限	20
VLLM_OPS_MCP_LIVE	実際のインフラでスモークテストを実行する場合は 1（「テスト」を参照）	未設定（スキップ）

使用例

// 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}}

テスト

CI（.github/workflows/ci.yml）は、プッシュまたはPRのたびにこのテストスイートを実行します（ubuntu-latest — 単体テストではHTTP／サブプロセスをモックするため、実サーバー／GPU／WSLは不要です）。また、上のTestsバッジの表示がテストスイートの実際の結果と異なる場合、ビルドを失敗させます。詳細は 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)

インストール

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

~/.claude.json に vllm-ops-mcp として登録されます（stdio、専用の .venv を使用。このオペレーターのデフォルト設定では環境変数の上書きは不要です）。

商用サポート

Jaimen Bell がメンテナンスしています。プロダクション環境でのMCP連携、カスタムサーバー、またはエージェントの信頼性向上に関する取り組みについては、jaimenbell.dev をご覧ください。

独自のMCPサーバーを構築していますか？ MCP Starter Kit には、このサーバーのリリースで得たテンプレート、構築ガイド、パッケージ化に関する実例が含まれています。

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