ugnas-mcp

ugnas-mcp

npx -y ugnas-mcp

UGREEN NAS デバイス上で動作する UGOS と、SSH（ファイル転送には SFTP）経由で通信する、汎用的な MCP（Model Context Protocol）サーバーです。

既存の UGREEN NAS 統合の多くとは異なり、ここにはハードコードされた値が一切ありません。固定 IP、サブネット、ユーザー名、共有名はありません。対象ごとの値はすべて設定から取得するため、同じサーバーを誰の NAS でも使用できます。

できること

NAS の所有者が日々の運用について実際に考える方法に合わせて整理されています。

グループ	ツール	変更を伴う操作か
接続とシステム	system.status, system.info, system.pools	読み取り専用
Docker	docker.containers.*（list/inspect/logs/start/stop/restart/remove）、docker.images.*（list/pull/remove）、docker.networks.*（list/inspect/create/remove/connect/disconnect）、docker.compose	start/stop/restart/pull/remove/create/compose は承認が必要
ファイルとデータ	files.list, files.usage, files.find, files.thumbnail, files.mkdir, files.copy, files.move, files.remove, files.upload, files.download, files.sync	thumbnail/mkdir/copy/move/remove/upload/download/sync は承認が必要
バックアップ	backup.create, backup.list, backup.verify, backup.restore, backup.schedule	create/restore/schedule は承認が必要
ネットワーク	network.interfaces, network.routes, network.ports	読み取り専用

ツールは合計 39 個です。 system.pools は、mdadm アレイと劣化状態、LVM ボリューム／論理ボリューム／物理ボリューム、btrfs デバイス、ブロックデバイス、ファイルシステムを報告します。

files.find は、名前の glob パターンや拡張子でディレクトリツリーを検索します（パス、サイズ、更新日時を返します）。files.thumbnail は、NAS 上の ffmpeg で画像または動画のフレームのプレビューを生成し、ローカルにダウンロードします。NAS のデータに対しては読み取り専用です（/tmp に一時ファイルのみを書き込み、削除します）が、ローカルマシンへのサムネイルの書き込みには承認が必要です。最初の呼び出しでドライラン計画が返され、トークンを使って確認するとローカルファイルが書き込まれます。NAS 上に ffmpeg が必要です（デフォルトで UGOS に含まれています）。

files.list と files.find は GNU coreutils のフラグ（ls --time-style=long-iso、find -printf）を優先します。これらが利用できない場合（BusyBox）は ls -1p と find -exec stat にフォールバックするため、動作を継続できます。ただし、BusyBox の ls でサイズや更新日時を取得できない場合は、これらの値は 0 になります。

files.sync と rsync フォールバック

files.sync は、NAS 間の高速で再開可能なコピーに rsync を使用します。--delete によるミラーリングと、rsync の --dry-run による事前チェックにも対応しています。UGOS には rsync がデフォルトでインストールされていないため、次のようになります。

• デフォルト（fallback: "refuse"） — rsync が見つからない場合でも、ドライラン計画には rsync コマンドが表示されますが、rsync のインストール方法（Entware：opkg install rsync）またはフォールバックの有効化方法を知らせる note が追加されます。確認するまで何も実行されません。
• オプトイン（fallback: "cp"） — 代わりに、ツールは組み込みの cp -a コピーにフォールバックします。計画の note でその旨を説明し、フォールバックで対応できない内容を warnings で示します。--delete によるミラーリングは行われず、rsync の --dry-run も使用されず、extraArgs は無視されます。

そのため、呼び出しごとに fallback: "cp" を渡すことでオプトインします。明示的に指定しない限り、何も変わりません。

安全モデル — まずドライランを実行し、その後に確認します

すべての変更を伴うツールには、次の2つのフェーズがあります。

1. トークンなしで呼び出す → ドライランの計画を返します。実行する予定の正確なシェルコマンド、 人間向けの概要、警告（ある場合）、有効期間の短い confirmationToken が含まれます。
2. confirmToken を指定して再度呼び出す → トークンが検証され（アクションに紐づけられ、1回のみ使用可能で、有効期限は 10分）、計画時に記録された正確なコマンドが実行されます。

読み取り専用のツールにはトークンは必要ありません。これにより、「データをコピーする」「このイメージを取得する」「あのコンテナを 再起動する」といった操作を、変更を加える前に確認できます。

ユーザーが指定した値（パス、コンテナ名、イメージタグ）は、リモートコマンドに埋め込む前にすべて POSIX シェル用に引用符で囲まれるため、 任意のコマンド実行につながるような形でコマンドを抜け出すことはできません。

確認時には、確認呼び出しの引数がトークンに記録された計画時の引数と照合されます。異なる場合、ツールは処理を拒否し、新しい計画を 取得するために再実行するよう求めます（古いトークンで引数の異なるアクションが実行されることはありません）。

設定

サーバーは ~/.ugnas-mcp/config.json から JSON 設定を読み込みます（UGNAS_MCP_CONFIG 環境変数で変更できます）。 config.example.json を参照してください。

{
  "name": "home-nas",
  "host": "192.168.1.50",
  "port": 22,
  "username": "admin",
  "auth": { "type": "key", "privateKeyPath": "~/.ssh/id_ed25519" },
  "defaultShare": "/volume1",
  "commandTimeoutMs": 60000
}

フィールド	必須	備考
host	はい	NAS の IP アドレスまたはホスト名です。
port	いいえ	SSH ポートです。デフォルトは 22 です。
username	はい	SSH ユーザーです。
auth	はい	{ "type": "key", "privateKeyPath": "..." }（推奨。passphrase に対応）または { "type": "password", "password": "..." } です。privateKeyPath にはインラインの PEM 形式の文字列も指定できます。
defaultShare	いいえ	相対ツールパスの基準ディレクトリです。デフォルトは /volume1 です。
sftpRoot	いいえ	SFTP サブシステムのルートディレクトリです。UGOS では SFTP のルートが共有フォルダーに制限されるため、/volume1/docker/x のような exec パスは、SFTP では /docker/x として指定する必要があります。ここには chroot ルートを設定してください（デフォルトは defaultShare です）。NAS で SFTP が chroot されない場合は "/" を使用してください。
hostKeySha256	いいえ	設定すると、SSH ホストキーが固定され、検証されます（例：SHA256:...）。比較時にパディングは無視されるため、ssh-keygen -lf が出力する正規のフィンガープリントをそのまま使用できます。
commandTimeoutMs	いいえ	コマンドごとのタイムアウトです。デフォルトは 60000 です。

環境変数によるオーバーライド

CI やシークレットの注入に便利です。環境変数の値はファイルの値より優先されます。

UGNAS_HOST=192.168.1.50
UGNAS_PORT=22
UGNAS_USER=admin
UGNAS_KEY_PATH=~/.ssh/id_ed25519      # or UGNAS_AUTH_TYPE=password + UGNAS_PASSWORD
UGNAS_DEFAULT_SHARE=/volume1
UGNAS_HOST_KEY_SHA256=SHA256:...

相対パスと絶対パス

ファイル／バックアップツールでは、どちらのパスも使用できます。絶対パスはそのまま使用され、相対パスは defaultShare に連結されます。

files.list("media")  ->  /volume1/media
files.list("/mnt/x")  ->  /mnt/x

インストールと実行

npm で ugnas-mcp として公開されています。直接実行できます。 クローンやビルドは不要です。

npx ugnas-mcp
# or install it once:
npm install -g ugnas-mcp
ugnas-mcp

これにより stdio MCP サーバーが起動します。設定は ~/.ugnas-mcp/config.json （または UGNAS_MCP_CONFIG ／ UGNAS_* 環境変数。詳しくは設定を参照）から読み込まれます。

MCP クライアントへの接続設定

クライアントで公式パッケージ（stdio）を指定します。

{
  "mcpServers": {
    "ugnas": {
      "command": "npx",
      "args": ["-y", "ugnas-mcp"],
      "env": { "UGNAS_MCP_CONFIG": "/absolute/path/to/config.json" }
    }
  }
}

または、グローバルにインストールした場合は、引数なしで "command": "ugnas-mcp" を指定します。

オプションの HTTP トランスポート

サーバーはデフォルトで stdio を使用します。UGNAS_HTTP_PORT を設定すると、ストリーミング可能な HTTP トランスポートも公開できます（両方が同時に動作します）。

UGNAS_HTTP_HOST=127.0.0.1 UGNAS_HTTP_PORT=4110 ugnas-mcp

• POST http://127.0.0.1:4110/mcp — JSON-RPC（ステートレス。リクエストごとに新しいセッションを作成し、本文の最大サイズは 1 MiB です）。
• GET http://127.0.0.1:4110/health — 稼働状態と接続先ホストを確認します。

デフォルトではループバックアドレスにバインドします。UGNAS_HTTP_ALLOW_REMOTE=1 も設定しない限り、 UGNAS_HTTP_HOST=0.0.0.0（またはループバック以外のアドレス）の指定は拒否されます。/mcp エンドポイントには認証がなく、 確認トークンはプロセス全体で共有されるため、ポートが別の方法（認証付きリバースプロキシ、VPN など）で保護されている場合に限り、 リモートアクセスを有効にしてください。

NAS の前提条件

• SSH が有効になっていること（UGOS：コントロールパネル → ターミナルと SNMP）。
• SSH ユーザーが docker を実行でき（docker グループに所属していること）、スケジュールバックアップを使用する場合は crontab を利用できること。
• tar、df、du、ip、ss は UGOS に標準で用意されています。
• backup.schedule のジョブ名には、単純な語（[A-Za-z0-9._-]）を使用してください。生成されるシェルスクリプトと crontab の行に埋め込まれるため、それ以外の文字は事前に拒否されます。
• rsync は任意で、files.sync でのみ使用されます。インストールされていない場合は、インストール方法または組み込みの cp フォールバックを有効にする方法（files.sync { fallback: "cp" }）を説明するメモが表示されます。それ以外のファイルツールはすべて rsync なしで動作します。

ライセンス

MIT — 詳細は LICENSE をご覧ください。コントリビューション、アーキテクチャ、開発・リリースのツールチェーンについては DEVELOPMENT.md をご覧ください。