アンレイドMCPサーバー

AI アシスタントが公式の Unraid GraphQL API を介して Unraid サーバーと対話できるようにする Python ベースの MCP (Model Context Protocol) サーバー。

免責事項

自己責任でご使用ください：このソフトウェアは、AIアシスタントを介してUnraidサーバーへのアクセスを提供します。この実装は安全性を高めるために読み取り専用に設定されていますが、ご使用の際はご注意ください。

• これは非公式ツールであり、Unraid, Inc. と提携しておらず、同社から承認も受けていません。
• システムの変更を防ぐため、すべての操作は読み取り専用に制限されています。
• 常にデータの適切なバックアップを維持する
• 行動を起こす前に、AIアシスタントが提供するすべての情報と提案を確認してください
• 開発者は、このソフトウェアの使用によって生じる可能性のある問題について一切責任を負いません。

読み取り専用アクセスであっても、監視ツールは機密性の高いシステム情報を漏洩させる可能性があります。本ソフトウェアを使用することで、お客様はこれらの制限とリスクを認識し、同意したものとみなされます。

特徴

• システム情報: Unraidサーバーの詳細情報を取得します
• アレイ管理: アレイのステータスを監視する
• Docker管理: Dockerコンテナとネットワークの一覧表示
• VM管理:仮想マシンの一覧表示
• ディスク情報: ディスクと未割り当てデバイスに関する詳細情報を取得します
• 通知管理: システム通知の表示と管理
• 共有管理: ネットワーク共有の表示と管理
• ユーザー管理: ユーザーの一覧
• APIキー管理: APIキーの一覧表示
• パリティ履歴: パリティチェックの履歴を表示する
• 共有: Unraid サーバー上のユーザー共有を参照します
• プラグイン: インストールされているプラグインとそのステータスを表示します
• エラー処理: 診断情報を含む包括的なエラー処理
• ログ記録: トラブルシューティングのための詳細なログ記録
• テンプレートリソース: 特定のコンテナとVMに名前でアクセスする

前提条件

• Python 3.10以降
• APIが有効になっているUnraidサーバー
• 適切な権限を持つAPIキー

インストール

Smithery経由でインストール

Smithery経由で Claude Desktop 用の Unraid MCP Server を自動的にインストールするには:

手動インストール

1. リポジトリをクローンします。
   git clone https://github.com/jmagar/unraid-mcp.git cd unraid-mcp
2. 仮想環境を作成してアクティブ化します。
   python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
3. 依存関係をインストールします:
   pip install -r requirements.txt
4. Unraid API 資格情報を使用して.envファイルを作成します。
   cp .env.template .env # Edit .env with your actual API URL and key

Unraid API セットアップ

この MCP サーバーを使用するには、Unraid サーバーに Unraid API を設定する必要があります。

1. CLI を使用して開発者モードと GraphQL サンドボックスを有効にします。
   unraid-api developer
   指示に従ってサンドボックスを有効にします。
2. 必要な権限を持つ API キーを作成します。
   unraid-api apikey --create
   プロンプトに従って、名前、説明、役割、および権限を設定します。
3. .envファイルを次のように構成します。
   • UNRAID_API_URL : GraphQL URL (例: http://your-unraid-server-ip/graphql )
   • UNRAID_API_KEY : 作成したAPIキー
4. http://your-unraid-server-ip/graphql GraphQL サンドボックスを使用して API をテストします。

注: Unraid API は、認証にベアラー トークンではなくx-api-keyヘッダーを使用します。

トラブルシューティング

• CORS エラーが発生した場合は、クライアントにサーバーの URL と一致する正しいOriginヘッダーが含まれていることを確認してください。
• 実行しようとしているクエリに必要なロールと権限が API キーにあることを確認してください。
• GraphQL サンドボックスが有効になっていてアクセス可能であることを確認します。

使用法

MCPサーバーの実行

AI アシスタントとの統合のために、サーバーを stdio モードで実行します。

stdio モードは次の場合に役立ちます。

• MCPプロトコルをサポートするAIアシスタントとの直接統合
• Anthropic Python SDK を使用したテスト
• カーソルでのClaudeとの統合

stdioモードで実行する場合、サーバーはMCPプロトコル形式に従って標準入力から読み取り、標準出力に書き込みます。これにより、HTTPトランスポートを必要とせずにAIアシスタントと直接通信できます。

サーバーアーキテクチャ

サーバーは FastMCP フレームワークを使用して構築され、次の要素で構成されます。

1. Unraid API クライアント( unraid_client.py ):
   • UnraidサーバーとのGraphQL通信を処理します
   • 認証とエラー処理を管理します
   • 一貫したエラー報告を提供する
2. MCP サーバー( server.py ):
   • MCP仕様に従ってリソースとツールを定義します
   • Unraidの機能をAIアシスタントに公開
   • リクエストの検証とエラー診断を処理します

利用可能なリソース

利用可能なツール

システム管理

アレイ管理

Docker管理

VM管理

通知管理

株式管理

ディスク管理

ユーザー管理

APIキー管理

クロードとの統合

Claude API または stdio モードをサポートする他の AI アシスタントで MCP サーバーを使用するには:

1. 設定ファイル (例: unraid_mcp_config.json ) を作成します。
   { "mcpServers": { "unraid": { "command": "/path/to/python", "args": ["/path/to/unraid-mcp/run_server.py"], "env": { "UNRAID_API_URL": "http://your-unraid-server:port/graphql", "UNRAID_API_KEY": "your-api-key", "LOG_LEVEL": "INFO", "CLAUDE_MCP_SERVER": "true" }, "disabled": false, "autoApprove": [] } } }

注意: Windows ユーザーの場合は、パスに必ず二重のバックスラッシュを使用してください (例: C:\\Users\\username\\unraid-mcp\\run_server.py )

クエリの例

• 「Unraid サーバーの現在の CPU 使用率はどれくらいですか?」
• 「すべてのDockerコンテナを一覧表示する」
• 「Plex コンテナについて教えてください」（container_details リソースを使用）
• 「Plexコンテナを起動する」
• 「アレイの状態はどうですか？」
• 「Unraid サーバーにはどれくらいの空き容量がありますか?」
• 「Windows VM の詳細を表示してください」（vm_details リソースを使用）
• 「どんなプラグインがインストールされていますか？」

トラブルシューティング

詳細なエラー情報については、ログ ファイル ( unraid_mcp.log ) を確認してください。

よくある問題:

• .envファイル内の API URL またはキーが正しくありません
• Unraidサーバーへのネットワーク接続の問題
• APIキーの権限が不十分です
• Unraid サーバーで開発者モードが有効になっていません
• APIキーに必要な役割がありません

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細については LICENSE ファイルを参照してください。

参考文献

• モデルコンテキストプロトコル
• MCP Python SDK
• Unraid API ドキュメント