Unraid MCP

ローカルModel Context Protocolサーバー。AIクライアントがUnraid公式GraphQL APIを通じてUnraidサーバーの調査・管理を行えるようにします。

AI支援開発の開示: このプロジェクトは、AIコーディングエージェントの多大な支援を受けて設計・調査・実装・文書化・テストされました。Unraidの公式プロジェクトではありません。Unraidサーバーへのアクセスを許可する前に、特にミューテーションツールを有効にする前に、ソースコード・権限・セキュリティ設定を自分自身で確認してください。

このMCPはデフォルトで読み取り専用です。ミューテーションツールは環境変数で明示的に有効化されるまで完全に省略され、恒久的・高リスクな操作には第二のゲートが設けられています。

要件

• Node.js 22以降

• pnpm 11

• APIがOSに組み込まれているUnraid 7.2以降

• Unraid APIキー

Unraid 7.0〜7.1ではUnraid Connectプラグインを通じてAPI v4を公開できますが、Unraidはこの組み合わせを限定サポートとして文書化しています。このプロジェクトのGraphQLドキュメントは、Unraid 7.3.2に同梱されているAPI v4.35.1を対象としています。古いAPIリリースでは、メトリクス・ログ・UPSフィールドなどの新しいクエリが拒否される場合があります。

Related MCP server: GraphQL MCP Toolkit

Unraidのセットアップ

1. Unraid WebGUIで設定 > 管理アクセス > APIキーを開きます。

2. このMCP用のキーを作成します。

3. 読み取り専用アクセスにはVIEWERロールから始めます。

4. 生成されたキーをUNRAID_API_KEYに保存します。ソース管理やコマンドライン引数には絶対に入れないでください。

同等のUnraidターミナルコマンドは次のとおりです:

unraid-api apikey --create --name "Unraid MCP read only" --roles VIEWER --json

ミューテーションアクセスには、ADMINよりもきめ細かい権限を優先してください。有効化するツールで使用するリソースのみを選択します。たとえばARRAY、DOCKER、VMS、NOTIFICATIONSを、READ_ANY、UPDATE_ANY、必要な場合にのみDELETE_ANYと組み合わせて選択します。

このMCPにGraphQLサンドボックスは不要です。スキーマのイントロスペクションも有効になるため、開発時以外は無効のままにしてください。

インストール

pnpm install --frozen-lockfile
pnpm build

依存関係は正確なバージョンで固定され、インストールはロックファイル固定です。pnpmはまた、公開から7日未満のリリース（公開時刻が不明なパッケージを含む）を拒否し、パッケージ/ストアの整合性を検証し、未宣言のライフサイクルスクリプトをブロックし、パッケージの信頼ダウングレードを拒否します。undici-types@6.21.0のバージョン固有の信頼例外は、固定された@types/nodeに必要です。年齢・整合性・ロックファイルのチェックはこのパッケージにも適用されます。依存関係を意図的に更新するには、レビューして検疫期間を待った後、正確なバージョンを使用し、ロックファイルの変更を明示的に許可してください:

pnpm update --exact --no-frozen-lockfile package-name@x.y.z
pnpm verify
pnpm audit

更新を受け入れる前にpackage.jsonとpnpm-lock.yamlの両方を確認してください。これらの管理を維持せずに自動依存関係更新ジョブを追加しないでください。

MCPを起動する環境で設定を構成します:

export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-api-key"
node /absolute/path/to/unraid-mcp/dist/index.js

UNRAID_URLはWebGUIのオリジン（この場合/graphqlが追加されます）または正確なGraphQLエンドポイントのいずれかです。最終的なHTTPS URLを直接設定してください。リダイレクトは拒否されるため、APIキーが別のオリジンに転送されることはありません。

コンテナイメージ

バージョン付きリリースイメージはlinux/amd64とlinux/arm64向けにDocker Hubで公開されています。デプロイメントでは変更可能なlatestタグに頼るのではなく、バージョンまたはイメージダイジェストを固定してください:

docker pull lemanjo/unraid-mcp:0.1.1

最終イメージはダイジェスト固定のDistroless Node.jsランタイムを使用します。シェル・パッケージマネージャー・npm・その他のビルドツールなしで、数値の非rootユーザーとして実行されます。コンテナビルドはTrivyでスキャンされ、修正可能な重大または高脆弱性が存在する場合はレジストリログイン前に失敗します。

Unraidサーバーまたは別のDockerホストで本番イメージをビルドします:

docker build --tag unraid-mcp:0.1.1 .

ローカルstdioコンテナ

デフォルトのトランスポートはstdioです。--env NAMEは、シークレットをイメージやコマンド引数に入れることなく、起動環境から値を転送します:

export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-api-key"

docker run --rm -i \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  unraid-mcp:0.1.1

オプションの設定も同様に転送します。たとえば--env UNRAID_ALLOW_MUTATIONSなどです。カスタムCAファイルの場合は、読み取り専用でマウントし、コンテナ内のパスを設定します:

docker run --rm -i \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  --env UNRAID_CA_CERT_PATH=/certs/unraid-ca.pem \
  --volume /host/path/unraid-ca.pem:/certs/unraid-ca.pem:ro \
  unraid-mcp:0.1.1

stdioモードではイメージはポートで待ち受けません。AIホストがdocker run --rm -iで起動し、そのライフサイクルを所有します。

常時稼働のリモートHTTPコンテナ

コンテナがAIクライアントとは別のマシンで実行される場合は、認証付きStreamable HTTPを使用します。信頼できるマシンで永続的なMCPトークンを生成します:

export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-unraid-api-key"
export MCP_ALLOWED_HOSTS="mcp-server.example,192.168.1.20"

リモートコンテナを起動します:

docker network create unraid-mcp-backend

docker run -d \
  --name unraid-mcp \
  --restart unless-stopped \
  --network unraid-mcp-backend \
  --env MCP_TRANSPORT=http \
  --env MCP_HOST=0.0.0.0 \
  --env MCP_PORT=3000 \
  --env MCP_ALLOWED_HOSTS \
  --env MCP_AUTH_TOKEN \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  unraid-mcp:0.1.1

IPv4またはIPv6ワイルドカードアドレスにバインドする場合、MCP_ALLOWED_HOSTSは必須です。クライアントまたはリバースプロキシがHTTP Hostヘッダーに配置するすべてのホスト名またはIPアドレスをリストします。エントリにポートは含めず、IPv6エントリは角括弧を使用します。ヘルスチェック用にlocalhost値は常に含まれます。

MCP_AUTH_TOKENを省略すると、サーバーは暗号的にランダムな256ビットトークンを生成し、起動時に一度だけ出力します:

docker logs unraid-mcp

Generated MCP auth token:を探してください。そのログを読める人は誰でもMCPにアクセスでき、変数が未設定のままの場合、プロセスが再起動するたびに新しいトークンが生成されます。安定した本番デプロイメントではMCP_AUTH_TOKENを明示的に設定してください。MCPトークンはUNRAID_API_KEYとは別です。リモートのAIクライアントはMCPトークンのみが必要です。

HTTPリスナーは意図的にプレーンHTTPです。この例ではポートを公開していません。Caddy、Nginx、Traefikコンテナをunraid-mcp-backendに参加させ、http://unraid-mcp:3000にプロキシしてください。ホストインストールのプロキシの場合、Docker 28以降は127.0.0.1:3000:3000を公開できます。古いDockerバージョン（一部のUnraidリリースを含む）では、localhost公開ポートが同じレイヤー2ネットワークに公開される可能性があるため、代わりにプライベートネットワークまたは明示的なファイアウォールルールを使用してください。ポート3000をインターネットに直接公開しないでください。コンテナのヘルスチェックはGET /healthを呼び出します。MCPトラフィックは/mcpを使用します。

組み込みの認証スロットルは直接のTCPピアを識別します。リバースプロキシの背後では、すべてのプロキシされたクライアントが1つのピアアドレスを共有する可能性があるため、プロキシ側でも認証レート制限を設定してください。信頼できないHost値を転送しないでください。外部ホスト名を保持してMCP_ALLOWED_HOSTSに含めるか、固定の許可リスト済みホスト名に書き換えてください。

ローカルDockerクライアント設定

Dockerデーモンを通じてイメージを起動するOpenCode設定は次のとおりです:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "local",
      "command": [
        "docker",
        "run",
        "--rm",
        "-i",
        "--env",
        "UNRAID_URL",
        "--env",
        "UNRAID_API_KEY",
        "unraid-mcp:0.1.1"
      ],
      "enabled": true,
      "environment": {
        "UNRAID_URL": "{env:UNRAID_URL}",
        "UNRAID_API_KEY": "{env:UNRAID_API_KEY}"
      }
    }
  }
}

AIホストが使用するDockerデーモンはイメージにアクセスできる必要があります。設定変更後はOpenCodeを再起動してください。

設定

UNRAID_CA_CERTまたはUNRAID_CA_CERT_PATHのどちらか一方を使用し、両方は使用しないでください。Unraidの証明書またはローカルCAを信頼することを優先してください。UNRAID_TLS_SKIP_VERIFY=trueは明示的な最後の手段であり、警告を出力します。他のNode.js接続のTLS動作をグローバルに変更するものではありません。

プレーンHTTPは隔離されたレガシーネットワーク向けにサポートされていますが、APIキーとすべてのサーバーデータが暗号化なしで送信されるため警告が出力されます。

AIクライアントのセットアップ

OpenCode

OpenCodeを起動する前に環境変数をエクスポートし、このローカルMCPをopencode.jsonに追加します:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "local",
      "command": ["node", "/absolute/path/to/unraid-mcp/dist/index.js"],
      "enabled": true,
      "environment": {
        "UNRAID_URL": "{env:UNRAID_URL}",
        "UNRAID_API_KEY": "{env:UNRAID_API_KEY}",
        "UNRAID_CA_CERT_PATH": "{env:UNRAID_CA_CERT_PATH}",
        "UNRAID_ALLOW_MUTATIONS": "{env:UNRAID_ALLOW_MUTATIONS}",
        "UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS": "{env:UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS}"
      }
    }
  }
}

未設定のオプション環境エントリは削除してください。設定変更後はOpenCodeを再起動します。

常時稼働のHTTPコンテナに接続するには、OpenCodeマシンにMCPトークンをエクスポートし、リモートサーバーを設定します:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "remote",
      "url": "https://mcp-server.example/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MCP_AUTH_TOKEN}"
      }
    }
  }
}

UnraidのGraphQL URLではなく、HTTPSリバースプロキシURLを使用してください。OpenCodeはMCP_AUTH_TOKENをMCPに送信します。UNRAID_API_KEYをUnraidに送信するのはMCPコンテナのみです。

Claude Code

Claude Codeを起動する前にUNRAID_URLとUNRAID_API_KEYをエクスポートします。プロジェクトスコープの場合は、Claude Codeを使用するプロジェクトに.mcp.jsonを作成します:

{
  "mcpServers": {
    "unraid": {
      "command": "node",
      "args": ["/absolute/path/to/unraid-mcp/dist/index.js"],
      "env": {
        "UNRAID_URL": "${UNRAID_URL}",
        "UNRAID_API_KEY": "${UNRAID_API_KEY}"
      }
    }
  }
}

Claude Codeは${VAR}参照を自身の環境から展開します。したがって、APIキーを保存せずに設定を共有できます。設定されている場合にのみオプション変数をenvに追加します。たとえば"UNRAID_ALLOW_MUTATIONS": "${UNRAID_ALLOW_MUTATIONS}"などです。

代わりにコンテナイメージを起動するには:

{
  "mcpServers": {
    "unraid": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env",
        "UNRAID_URL",
        "--env",
        "UNRAID_API_KEY",
        "unraid-mcp:0.1.1"
      ],
      "env": {
        "UNRAID_URL": "${UNRAID_URL}",
        "UNRAID_API_KEY": "${UNRAID_API_KEY}"
      }
    }
  }
}

claude mcp listを実行してサーバーを確認し、Claude Code内で/mcpを使用してステータスとツールを検査します。Claude Codeはプロジェクトスコープの.mcp.jsonサーバーを使用する前に承認を求めます。プライベートなクロスプロジェクト設定を~/.claude.jsonで希望する場合は、Claude CodeのMCPコマンドで--scope userを使用してください。

常時稼働のHTTPコンテナの場合は、代わりにこの.mcp.jsonエントリを使用します:

{
  "mcpServers": {
    "unraid": {
      "type": "http",
      "url": "https://mcp-server.example/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_AUTH_TOKEN}"
      }
    }
  }
}

Claude Codeを起動する前にMCP_AUTH_TOKENをエクスポートします。${MCP_AUTH_TOKEN}参照は、プロジェクト設定に値を保存せずに展開されます。

Codex CLIおよびIDE

Codex CLI、Codex IDE拡張機能、ChatGPTデスクトップアプリはMCP設定を共有します。必要な変数をエクスポートし、このエントリを~/.codex/config.toml、または信頼されたプロジェクトの.codex/config.tomlに追加します:

[mcp_servers.unraid]
command = "node"
args = ["/absolute/path/to/unraid-mcp/dist/index.js"]
env_vars = ["UNRAID_URL", "UNRAID_API_KEY"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

env_varsは、config.tomlに書き込むことなくCodexの環境から値を転送します。有効化したオプション設定（UNRAID_CA_CERT_PATHやUNRAID_ALLOW_MUTATIONSなど）をそのリストに追加してください。

代わりにコンテナイメージを起動するには:

[mcp_servers.unraid]
command = "docker"
args = [
  "run",
  "--rm",
  "-i",
  "--env",
  "UNRAID_URL",
  "--env",
  "UNRAID_API_KEY",
  "unraid-mcp:0.1.1",
]
env_vars = ["UNRAID_URL", "UNRAID_API_KEY"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

writes承認モードは、読み取り専用とマークされていないツールに対してプロンプトを表示します。codex mcp listを実行してサーバーを確認し、Codex TUIで/mcpを使用して接続済みツールを検査してください。共有設定を編集した後は、IDE拡張機能またはChatGPTデスクトップアプリを再起動してください。

常時稼働のHTTPコンテナの場合は、代わりに次のエントリを使用します:

[mcp_servers.unraid]
url = "https://mcp-server.example/mcp"
bearer_token_env_var = "MCP_AUTH_TOKEN"
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

Codexはベアラートークンをローカル環境から読み取り、その値をconfig.tomlに保存しません。

Claude Desktopおよびその他のstdioホスト

ホストが以下を起動するように設定します:

node /absolute/path/to/unraid-mcp/dist/index.js

ホストプロセスに、OS、サービス管理ツール、またはシークレットマネージャーから必要な環境変数を継承させてください。APIキーをargs配列に配置しないでください。ホストがサーバーごとの環境値をサポートしているがシークレット参照をサポートしていない場合、それらの値はそのホストの設定ファイルに保存されることを理解してください。

MCP Inspector

変数をエクスポートした状態で、ツールを対話的に検査および呼び出します:

pnpm dlx @modelcontextprotocol/inspector node dist/index.js

Inspectorは意図的にプロジェクトの依存関係ではありません。環境に承認されたバージョンを呼び出してください。

ツール

以下の読み取りツールは常に登録されます:

UNRAID_ALLOW_MUTATIONS=trueで以下が追加されます:

UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS=trueでさらに以下が追加されます:

また、unraid_control_parity_checkがcorrect=trueで開始することも許可されます。

MCPアノテーションはクライアントへのヒントであり、アクセス制御ではありません。環境ゲートとUnraid APIキー自身の権限が実際の制御です。

APIの制限事項

現在の公式スキーマは、すべてのWebGUI操作を提供しているわけではありません。具体的には:

• 共有は読み取り専用です。共有の作成/編集は利用できません。

• Dockerコンテナは制御、更新、削除が可能ですが、作成や編集はできません。

• VMは制御可能ですが、作成、編集、クローン、スナップショット、削除はできません。

• ホストのシャットダウン/再起動の変更操作は公開されていません。

• 完全なSMARTレポートとSMARTセルフテストの制御は公開されていません。

• DockerのrestartはAPI v4.35.1以降に追加され、この互換性ターゲットでは意図的に使用されません。

• パリティ変更の応答タイプは、Unraidによって作業中とマークされています。

公式のソース参照と互換性の詳細については、docs/api-capabilities.mdを参照してください。

開発

pnpm typecheck
pnpm test
pnpm build
# Or run all three:
pnpm verify

テストはローカルのモックHTTPサーバーと、インメモリおよびStreamable HTTP MCPクライアントを使用します。Dockerや稼働中のUnraidサーバーは必要ありません。

コンテナリリース

GitHub Actionsは、プルリクエストとmainへの変更に対して、レジストリ認証情報を使用せずにコンテナをビルドし、脆弱性スキャンを実行します。公開は、v0.1.1などのセマンティックバージョンのGitHub Releaseが公開された場合のみ行われます。リリースワークフローは、保護されたdockerhub環境のDOCKERHUB_TOKENにアクセスする前にビルド済みイメージをスキャンし、その後、SBOMと来歴証明書付きでバージョン、コミット、および(安定版リリースの場合)latestタグを公開します。

セキュリティに関する注意事項

• Stdioがデフォルトのままであり、リッスンするネットワークポートを開きません。

• HTTPモードではベアラー認証が必要です。トークンが欠落している場合は、256ビットの暗号論的乱数で生成され、意図的に起動ログに書き込まれます。

• 生成されたトークンは運用上のシークレットです。ログへのアクセスを制限し、安定したデプロイメントのためにMCP_AUTH_TOKENを設定してください。

• HTTPモードはHostヘッダーとOriginヘッダーを検証し、失敗した認証をレート制限し、リクエストボディを制限し、デフォルトでループバックバインドを使用します。

• 組み込みのHTTPリスナーはTLSを提供しません。HTTPSリバースプロキシを使用し、インターネットに直接公開しないでください。

• アプリケーションログをstdoutに書き込むことはありません。stdoutはMCP JSON-RPC用に予約されています。

• モデルからの任意のGraphQLドキュメントを受け入れません。

• リダイレクトに従わず、応答サイズ、ログ行数、リクエスト時間を制限します。

• クライアントのキャンセルはローカルHTTPリクエストを中止します。Unraidがすでに受け入れた変更操作はロールバックできません。

• GraphQLエラーに設定されたAPIキーが含まれている場合、そのエラーは編集されます。

• ディスクのシリアル番号、ログ、通知、ネットワークアドレス、その他のサーバーデータは、接続されたAIクライアントに表示されます。そのクライアントのデータ処理ポリシーを確認してください。

公式リファレンス

• Unraid API概要

• Unraid APIの使用方法

• プログラムによるAPIキー管理

• Unraid APIロードマップとバージョンサポート

• API v4.35.1生成GraphQLスキーマ

• Unraid接続セキュリティガイダンス

• MCP TypeScript SDK stdioガイダンス

• MCP TypeScript SDK Streamable HTTPガイダンス

• Claude Code MCP設定

• Codex MCP設定

ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。