longhorn-mcp

longhorn-mcp

Longhorn 分散ストレージマネージャー API 用の MCP サーバーです。Longhorn REST API（ボリューム、スナップショット、バックアップ、バッキングイメージ、ノード、設定、エンジンイメージ、定期ジョブなど）を完全に読み書きでき、--read-only モード、stdio と Streamable HTTP の両方のトランスポート、公式 Helm チャートに対応しています。

AI 支援による開発です。 このコードベースの大部分（実装、テスト、ドキュメント）は AI（Claude）の支援を受けて作成されました。特に、本番環境の Longhorn クラスターに対して書き込みモードのツールを実行する前に、十分に確認してください。

クイックスタート

npx -y longhorn-mcp --longhorn-url=http://<longhorn-manager-host>:9500

Longhorn のマネージャー API は認証されていません。アクセス制御は到達可能かどうかだけです。クラスター内の Longhorn に接続していない場合（一般的な MCP クライアントの接続 → リモート／HTTP を参照）は、安全に接続するために VPN、SSH トンネル、または kubectl port-forward svc/longhorn-backend 9500:9500 が必要です。Longhorn のマネージャー API を、信頼できないネットワークに直接公開しないでください。

CLI リファレンス

フラグ	デフォルト	説明
--http	オフ（stdio）	stdio の代わりに Streamable HTTP でサービスを提供します。
--port	3000	HTTP リッスンポート（--http 使用時）。
--host	0.0.0.0	HTTP リッスンアドレス（--http 使用時）。
--read-only	オフ	読み取り専用ツールのみを登録します。クライアントも GET 以外のリクエストを拒否します。
--longhorn-url	http://longhorn-backend.longhorn-system.svc.cluster.local:9500	Longhorn マネージャー API のベース URL です。デフォルトでは標準の Kubernetes クラスター内 DNS を使用します。カスタムのクラスター ドメインを持つクラスターでは、このパッケージのデフォルトを変更するのではなく、独自の Deployment で --longhorn-url を指定して上書きしてください。
--allowed-hosts	localhost,127.0.0.1	--http モードでの Host／Origin 許可リスト（カンマ区切り）です。サーバーへの実際の接続に使われるすべてのホスト名／IP:ポートを含める必要があります。MCP 仕様の DNS リバインディングに関するガイダンスを参照してください。

Helm を使用したデプロイ

公式チャートは各リリースとともに公開されています。

helm install longhorn-mcp oci://ghcr.io/rafaelgaspar/longhorn-mcp/charts/longhorn-mcp --version 0.1.0 \
  --set args[0]=--http \
  --set args[1]=--longhorn-url=http://longhorn-backend.longhorn-system.svc.cluster.local:9500

主な値：

値	デフォルト	備考
image.repository / image.tag	ghcr.io/rafaelgaspar/longhorn-mcp / チャートの appVersion
args	["--http"]	--read-only、--longhorn-url、--allowed-hosts などを追加します。CLI リファレンスを参照してください。
service.enabled / .type / .port	true / ClusterIP / 3000
route.enabled	false	オプションの、ベンダー中立なコア Gateway API HTTPRoute（gateway.networking.k8s.io/v1）です。Envoy Gateway 固有のリソースは使用しません。独自の Gateway を用意し、route.parentRefs／route.hostnames を設定してください。
serviceAccount.create	true

完全なスキーマ： chart/values.yaml ／ chart/values.schema.json。

このチャートは、別途タグ付けされたアーティファクトを取得するのではなく、OCI Referrers API を使ってチャートを検出するツール向けに、イメージマニフェスト上の OCI リファラーとしても添付されています。

oras discover ghcr.io/rafaelgaspar/longhorn-mcp:0.1.0

一般的な MCP クライアントの接続

各クライアントの正確な設定ファイルのパスやキーは、バージョンによって変わることがあります。これらの設定で動作しない場合は、クライアントの公式ドキュメントを確認してください。いずれも、ローカル stdio サーバーには同じ command／args の形式を使用できます。

Claude Code

claude mcp add longhorn -- npx -y longhorn-mcp --longhorn-url=http://localhost:9500

Claude Desktop

claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "longhorn": {
      "command": "npx",
      "args": ["-y", "longhorn-mcp", "--longhorn-url=http://localhost:9500"]
    }
  }
}

Cursor

.cursor/mcp.json（プロジェクト単位）または ~/.cursor/mcp.json（グローバル）を編集します。

{
  "mcpServers": {
    "longhorn": {
      "command": "npx",
      "args": ["-y", "longhorn-mcp", "--longhorn-url=http://localhost:9500"]
    }
  }
}

VS Code（Copilot Chat）

.vscode/mcp.json では、mcpServers ではなく servers キーを使用します。

{
  "servers": {
    "longhorn": {
      "command": "npx",
      "args": ["-y", "longhorn-mcp", "--longhorn-url=http://localhost:9500"]
    }
  }
}

リモート／HTTP

すでに稼働している Streamable HTTP インスタンス（例：このサーバーをクラスター内にデプロイしたもの。詳しくはHelm を使ったデプロイを参照）をクライアントに指定し、ローカルで npx プロセスを起動しないようにするには、そのクライアントのリモート MCP 設定で、サーバーの /mcp URL を使用してください。ネイティブのリモート HTTP MCP に対応していないクライアントは、mcp-remote を使って中継できます。

ゲートウェイの背後で実行する

Longhorn のマネージャー API（ひいてはこのサーバー自体）には認証機能がありません。アクセス制御は到達可能性によって行われます（クイックスタートを参照）。マルチテナント環境や外部からアクセス可能な環境にデプロイする場合、認証、レート制限、ルーティングのために、--http モードを MCP 対応ゲートウェイ（例：Envoy AI Gateway など）の背後に置くことをお勧めします。ただし、これは必須ではありません。プライベートネットワーク境界（VPN、SSH トンネル、クラスター内部のみ）も十分に妥当な単独の構成であり、Helm チャートのデフォルト設定もまさにこの構成です（route.enabled: false、外部公開なし）。

破壊的操作のガードレール

--read-only は強制される構造的な保証です（以下を参照）。これに対して、次の仕組みはより緩やかな、モデル向けのものです。適切に動作する LLM が何をすべきかを示すものであり、サーバーが何を拒否できるかを定めるものではありません。

破壊的、または取り消しが困難な操作（削除、強制デタッチ、リバート、クラスター全体の状態の復元、ノードの退避、任意のエンジンイメージのデプロイ、バックアップ先の変更など）を実行する各ツールの説明には、現在の会話でユーザーがその特定の操作を明示的に許可していない限り、決して呼び出さないこと、また先回りして、推測で、あるいは無関係なタスクの副作用として実行しないことが明記されています。この指針はサーバーの MCP instructions フィールドにも記載されており（この機能に対応するクライアントでは各ツールの説明に加えて表示されます）、ツールの説明全体を注意深く読まずに呼び出す場合に備えた、サーバーレベルの補完策となっています。

これは助言であり、強制されるものではありません。クライアントやモデルは無視できます。これにより、LLM が求められていない「親切な」副作用として volume_delete や systemrestore_create を呼び出す可能性は低くなりますが、必要とする保証がそれである場合に --read-only の代わりにはなりません。

Longhorn のドキュメントリンク

ほとんどのツールの説明の末尾には、該当ページを示す Longhorn docs: <url> リンクがあります。このリンク先はLonghorn の公式ドキュメントで、このサーバーのデフォルトの --longhorn-url の接続先が実行する Longhorn のバージョン（現在は 1.13.0）に固定されており、「latest」には設定されていません。これにより、リンク先の内容が実際に使用中の API バージョンと一致します。明確に対応するドキュメントページがない一部のツール（instancemanager_*、volumeattachment_*、longhorn_events、volume_job_list、および longhorn_raw_request／longhorn_list_resource_types／longhorn_describe_resource_type イントロスペクションツール）には、リンクがありません。

アクションリンク

このサーバーが返す Longhorn リソース（ボリューム、ノード、バックアップイメージなど）にはそれぞれ、そのリソースで現在有効な RPC アクションを示す actions マップが含まれています。たとえば、ボリュームの actions.attach です。Longhorn 自身の API は、これらをマネージャーのクラスター内アドレスを指す URL として返しますが、ツールしか呼び出せず、任意の HTTP エンドポイントは呼び出せない MCP クライアントには役立ちません。このサーバーは代わりに、それぞれを実行する MCP ツールへ書き換え、そのツールのパラメーター形式（名前 -> 簡潔な型、省略可能な場合は ? サフィックス）も併記するため、クライアントは別途スキーマを参照せずに呼び出せます。たとえば次のとおりです。

"actions": {
  "attach": {
    "tool": "volume_attach",
    "shape": { "name": "string", "hostId": "string", "disableFrontend": "boolean?", "attachedBy": "string?", "attacherType": "string?", "attachmentID": "string?" }
  },
  "updateReplicaCount": {
    "tool": "volume_update_setting",
    "shape": { "name": "string", "setting": "enum(19 values)", "value": "string|number|boolean" },
    "args": { "setting": "replicaCount" }
  }
}

args（上記の updateReplicaCount のようなもの）は、アクションによってツールのパラメーターのいずれかがすでに指定されている場合に表示されます。Longhorn の約 19 個の単一フィールドのボリューム update* アクションは、すべて 1 つの volume_update_setting ツールを経由し、渡す setting の値だけで区別されます。shape には、args で指定済みのものも含め、ツールが受け取るすべてのパラメーターが常に記載されるため、別途参照しなくても、指定済みの値を常に shape と照合できます。

各リソース型のスキーマで現在定義されているすべてのアクションは、この方法で名前付きツールに対応付けられています。これには、volume_job_list を介して呼び出す、ドキュメント化されていないボリュームの jobList も含まれます（Longhorn はこのアクションの入力／出力スキーマを公開していないため、このツールは自由形式の extra オブジェクトを受け取ります。デプロイされたバージョンの正確な形式は longhorn_describe_resource_type('volume') で確認してください）。今後の Longhorn バージョンで追加され、このサーバーがまだ対応していないアクションは、代わりに longhorn_raw_request にフォールバックし、元の URL の args.method／args.path があらかじめ入力されます。Longhorn はリソースの状態で現在有効なアクションのみを列挙するため（たとえば salvage は障害状態のボリュームにのみ表示されます）、これはツールのスキーマで許可されているだけでなく、現時点で実際に呼び出し可能なものを反映しています。

読み取り専用モード

--read-only は、次の 2 つの方法で読み取り専用を強制します。

1. 登録時のフィルタリング — 書き込みツールは一切 tools/list に通知されないため、読み取り専用インスタンスのツールセットは読み取り／書き込みインスタンスの厳密な部分集合になります。
2. クライアント層のガード — LonghornClient は、どのツールが呼び出したかにかかわらず、GET 以外のリクエストを拒否します。両方のモードで登録されたままの唯一の抜け道ツール longhorn_raw_request を保護するのはこの仕組みです（書き込み操作かどうかは、実際に呼び出されるまでわかりません）。

同じクライアント設定内で、読み取り／書き込みインスタンスと読み取り専用インスタンスを異なる名前で実行すると、LLM セッションの既定を読み取り専用にしつつ、明示的に利用できる書き込み対応ツールセットも別名で用意できます。

{
  "mcpServers": {
    "longhorn": { "command": "npx", "args": ["-y", "longhorn-mcp", "--longhorn-url=http://localhost:9500"] },
    "longhorn-readonly": { "command": "npx", "args": ["-y", "longhorn-mcp", "--read-only", "--longhorn-url=http://localhost:9500"] }
  }
}

開発

npm ci
npm run typecheck
npm test
npm run build

scripts/introspect-schema.ts は、Longhorn マネージャーの /v1/schemas の自己記述内容をライブで出力します。実際に実行している Longhorn バージョンに対して、このパッケージで手作業により網羅したツールの対応状況を照合するのに便利です。

npm run introspect-schema -- http://localhost:9500
npm run introspect-schema -- http://localhost:9500 volume   # one resource type in full

コントリビューション

コントリビューションを歓迎します。開発環境のセットアップ、コーディング規約、リリースの仕組みについては、CONTRIBUTING.md をご覧ください。

ライセンス

MIT — LICENSE をご覧ください。