Unraid MCP

Unraid

Unraid ツールをまとめたモノレポです。2 つの MCP サーバー（Python と Rust）と 3 つの Unraid OS プラグインに加え、それらを利用する Claude/Codex エージェント連携を含みます。

リポジトリ名。 このリポジトリは 2026-07-27 に unraid-mcp から unraid に名称変更され、以前は独立していた runraid と incus-unraid のリポジトリも統合されました。一部のデプロイ済みプラグインのインストール／更新 URL は、引き続き旧名称からのリダイレクトに依存しています。これらの実行時 URL の移行には、意図的なリリースが必要です。PyPI パッケージ、コンテナーイメージ、Claude プラグイン、Unraid .plg の名称はすべて引き続き unraid-mcp です。変更されたのはリポジトリ名のみです。

コンポーネント

パス	内容	ツールチェーン	ビルド／テスト
unraid-py/	unraid-mcp — Python MCP サーバー（GraphQL）、主要コンポーネントです。PyPI では unraid-mcp として公開されています。	Python / uv / hatchling	cd unraid-py && uv run pytest && uv build --wheel
unraid-rs/	runraid — Rust MCP サーバーと CLI（単一の静的バイナリ）です。crates.io ではクレート unraid-rmcp として公開され、互換性のための npm ランチャー @dinglebear/unraid もあります。	Rust / cargo	cd unraid-rs && cargo fmt --check && cargo clippy --all-targets --features test-support -- -D warnings && cargo test
plugins/mcp/	Rust 製の runraid MCP サーバーを Unraid マシンに導入する Unraid OS プラグインです。	shell .plg + Rust + Vue	bash plugins/mcp/scripts/build-txz.sh <ver> <runraid-binary>
plugins/incus/	LAN からファイアウォールで隔離された Incus システムコンテナー（「dev containers」）を実行する Unraid OS プラグインです。NestJS/GraphQL の unraid-api バックエンドを含みます。	shell .plg + NestJS/Vue	cd plugins/incus && ./scripts/verify-classic-package.sh && ./tests/classic-contract.sh
plugins/codex/	Codex チャットヘッドの app-server を組み込んだ Unraid OS プラグインです。	shell .plg + React	cd plugins/codex && ./tests/contract.sh
agents/unraid-py/	Python サーバー用の Claude Code / Codex プラグイン（name: unraid-mcp）です。	—	—
agents/unraid-rs/	Rust サーバー用の Claude Code / Codex プラグイン（name: runraid）です。	—	—

エージェントプラグインのインストール（1 つのマーケットプレイスコマンド、2 つのマニフェスト）

/plugin marketplace add dinglebear-ai/unraid
/plugin install unraid-mcp@unraid-mcp   # Python server
/plugin install runraid@unraid-mcp      # Rust server

@unraid-mcp サフィックスは .claude-plugin/marketplace.json で宣言されているマーケットプレイス名であり、リポジトリ名ではありません。リポジトリが dinglebear-ai/unraid になった後も、unraid-mcp のままです。

両方のプラグインは、1 つのリポジトリから公開されます。Claude は .claude-plugin/marketplace.json を読み取り、Codex は .agents/plugins/marketplace.json を読み取ります。 meta-ci.yml により、両方に同じプラグインセットが記載されていることが検証されるため、内容が食い違うことはありません。

marketplace add には、owner/repo 形式の省略表記（または完全な Git URL／ローカルパス）を指定できます。インストール後、Claude Code が接続設定（プラグインの userConfig）を求めます。

プラグインの認証情報に手動の設定は不要です

エージェントプラグインには Claude Code フックは含まれておらず、必要もありません。両方の .mcp.json ファイルが ${user_config.*} を介して、プラグイン設定をサーバー環境に直接割り当てます。agents/unraid-rs はエンドポイント、TLS、認証、ツールセレクターの設定を割り当て、agents/unraid-py は UNRAID_API_URL と UNRAID_API_KEY を割り当てます。プラグイン設定で値を設定すると、サーバーは次回の起動時にそれらを読み込みます。

任意の設定です。ディスクに ~/.unraid/.env を書き込む必要があるプラグイン以外のインストール（systemd、Docker）向けです。

runraid setup plugin-hook          # or: npx -y @dinglebear/unraid setup plugin-hook

unraid-py クイックスタート（Python MCP サーバー）

Python サーバーが主力です。インストール、Claude Code ／ Codex ／ Gemini のセットアップ、設定、認証、ガードレール、ツールの一覧を含む完全なドキュメントは、unraid-py/README.md と unraid-py/docs/ にあります。PyPI には unraid-mcp（インポート パッケージは unraid_mcp）として公開され、uvx unraid-mcp で起動します。

unraid-rs クイックスタート（Rust MCP サーバー＋CLI）

cargo install --path unraid-rs --locked     # from the repository root
# Configure UNRAID_API_URL and UNRAID_API_KEY privately before querying.
runraid setup check                        # inspect setup without repairing files
runraid array                              # read array state
runraid serve mcp                          # MCP HTTP (default :40010; configure auth)

環境変数	用途
UNRAID_API_URL	Unraid GraphQL エンドポイント（必須）
UNRAID_API_KEY	Unraid API の x-api-key（必須）
UNRAID_API_SKIP_TLS_VERIFY	自己署名 Unraid 証明書を許可します（既定値は false）
UNRAID_RMCP_HOST / UNRAID_RMCP_PORT	MCP のバインドアドレス（既定値は 0.0.0.0:40010）
UNRAID_RMCP_TOKEN	/mcp 用の静的ベアラートークン
UNRAID_RMCP_AUTH_MODE	bearer（既定値）または oauth

全項目と OAuth 関連の環境変数については、unraid-rs/AGENTS.md を参照してください。

読み取り専用ではありません。 Rust サーバーはクエリとミューテーションの両方を公開します。読み取りアクションには unraid:read スコープが必要です。変更を伴うアクション（VM と Docker のライフサイクル、アレイの起動／停止、通知の書き込み）には unraid:admin が必要です。

開発とドキュメント

まず、貢献者向けの正式なガイドである AGENTS.md を確認してください。 CLAUDE.md と GEMINI.md は、各コンポーネント内のものも含めて、このファイルへのシンボリックリンクです。 ドキュメントインデックスから、 開発と検証、 アーキテクチャ、リリース手順を参照できます。

Rust MCP は UNRAID_RMCP_PROJECTION=legacy（既定値）、atomic、または both をサポートします。 どのプロジェクションも、有効化されたアクションのポリシー、スコープ、実行処理を共有します。atomic モードは別のバックエンドではありません。セレクターと移行については、Rust の README を参照してください。

リリース

リリースの流れは 2 つあります。release-please が管理するのは unraid-py と unraid-rs のみです。Python サーバーでは、既存の利用者向けの方式として、接頭辞なしの vX.Y.Z タグを引き続き使用します。Rust では unraid-rs-vX.Y.Z を使用します。Incus と Codex のプラグインでは release-please を使用しません。これらのバージョンは .github/scripts/plugin_calver.py によって、固定幅の YYYYMMDD.NNN 形式で管理され、incus-v* ／ codex-v* タグを使用します（Unraid はプラグインのバージョンを文字列として比較するため、固定幅が必須です）。

ネイティブ MCP プラグインは、対応する unraid-rs-vX.Y.Z タグからビルドされます。Community Applications は、unraid-plugin-latest リリースから最新のマニフェストを読み込みます。プラグインの .txz ペイロードは GitHub の リリースアセットとして配布し、Git では管理しません。

ライセンス

MIT — LICENSE を参照してください。