synology-filestation-mcp

Synology File Station Web API をベースにした MCP (Model Context Protocol) サービス。AI エージェントが Synology NAS 上のファイルを直接管理できるようになります：ディレクトリ参照、検索、アップロード/ダウンロード、作成/名前変更/コピー/移動/削除、圧縮/解凍など。

2つの実行モードをサポート：

• stdio ローカルモード（src/index.js）：個人のPCで実行し、認証情報はローカルの環境変数に保管

• Streamable HTTP リモートモード（src/http.js）：サーバーに集中デプロイし、複数のユーザーで共有。各ユーザーのNAS認証情報はリクエストヘッダーで渡します

環境要件

• Node.js >= 18（開発は Node 24 で検証；低い glibc のサーバーは unofficial-builds の glibc-217 ビルドを使用可能）

• DSM 7.x（DSM 7.2 で実測済み）

Related MCP server: Synology MCP Server

インストール

npm install

モード1：stdio ローカルモード

環境変数でNAS接続情報を提供（.env.example を .env にコピーして記入し、起動時に自動読み込みも可能）：

Claude Desktop を例に、claude_desktop_config.json を設定：

{
  "mcpServers": {
    "synology-filestation": {
      "command": "node",
      "args": ["D:/path/to/synology-filestation-mcp/src/index.js"],
      "env": {
        "SYNOLOGY_HOST": "http://192.168.1.1:5000",
        "SYNOLOGY_USER": "your_username",
        "SYNOLOGY_PASSWORD": "your_password"
      }
    }
  }
}

モード2：HTTP リモートモード（複数ユーザー共有）

サーバー起動：

# .env 或环境变量
SYNOLOGY_HOST=http://192.168.1.1:5000   # 默认 NAS 地址（客户端可用 X-NAS-Host 覆盖）
PORT=3000
MCP_AUTH_TOKEN=<随机令牌>                # 设置后客户端必须带 Bearer token

npm run start:http

特徴：

• マルチユーザー：各 MCP セッションが独立した NAS ログイン状態（sid プール）を保持し、相互に混在しない

• 認証情報の受け渡し：クライアントはリクエストヘッダーで自分のNASアカウント X-NAS-User / X-NAS-Password を指定。オプションで X-NAS-Host によりサーバーのデフォルトを上書き可能。省略時はサーバーの環境変数にフォールバック（サーバー側でアカウントを一元管理する場合に対応）

• 認証：MCP_AUTH_TOKEN を設定すると、すべての /mcp リクエストに Authorization: Bearer <token> が必要

• セッション管理：アイドル状態が30分経過すると自動的にセッションをクリーンアップしNASからログアウト（SESSION_IDLE_TTL_MS で調整可能）

• ヘルスチェック：GET /health

クライアント設定（リモート MCP 対応クライアント、url 方式）：

{
  "mcpServers": {
    "synology-filestation": {
      "url": "http://<部署服务器>:3000/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_AUTH_TOKEN>",
        "X-NAS-User": "同事自己的 NAS 账号",
        "X-NAS-Password": "同事自己的 NAS 密码"
      }
    }
  }
}

systemd デプロイ例：

[Unit]
Description=Synology FileStation MCP (HTTP)
After=network.target

[Service]
WorkingDirectory=/opt/synology-filestation-mcp
ExecStart=/usr/bin/node src/http.js
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

セキュリティ注意：本番環境では HTTPS（リバースプロキシ）で TLS を終端し、NAS認証情報がリクエストヘッダーで平文送信されないように推奨。

ツール一覧

テスト

SYNOLOGY_HOST=http://192.168.0.196:5000 SYNOLOGY_USER=xxx SYNOLOGY_PASSWORD=xxx npm test

スモークテストでは NAS に対して完全なパスを実行：ログイン → 共有フォルダ一覧 → ディレクトリ作成 → アップロード → 一覧 → 情報取得 → 名前変更 → コピー → 検索 → ダウンロード内容検証 → 削除クリーンアップ → ログアウト。テストは書き込み可能な共有フォルダの下に mcp-smoke-test 一時ディレクトリを作成し、終了後に自動削除されます。

拡張機能テスト test/extended.mjs もあり（node test/extended.mjs、同様に環境変数を読み込み）：23種類のファイル形式（ドキュメント/画像/動画/音声/アーカイブ/データベース/仮想マシンイメージ）のアップロード/ダウンロードバイト単位検証、バッチコピー/移動/削除、NAS 上での解凍、ごみ箱保存先確認、および権限とセキュリティの能力境界探索をカバー。

実装説明（DSM 7.x 互換性）

• 起動時に SYNO.API.Info を呼び出して各 API のパスとバージョンを検出、ログインは SYNO.API.Auth（format=sid）を使用。

• SYNO.FileStation.List v2 の additional パラメータは JSON 配列形式（例：["size","time"]）が必要。カンマ区切り文字列は静かに無視される。

• ファイル情報の取得には SYNO.FileStation.List / getinfo を使用（SYNO.FileStation.Info / get は File Station サーバーの設定を返すもので、ファイル情報ではない）。

• アップロードには API version 2 を使用：実測では v3 では overwrite パラメータが効かず、同名ファイルで 414 が返る。アップロード時は sid をフォームフィールドと Cookie: id=<sid> の二重経路で渡す。

• コピー/移動/削除は非同期タスク。DSM 7.x の SYNO.FileStation.BackgroundTask は list メソッドのみ（status はなし）。taskid でフィルタして進捗を照会する。

• 検索は非同期タスク。ツール内部で list をポーリングし finished になるまで待機。

• SYNO.FileStation.Extract の対象ディレクトリは事前に存在している必要がある。存在しない場合は 408（No such file or directory）が返る。

• SYNO.FileStation.Compress はアカウントの DSM アプリケーション権限に依存。105（session does not have permission）が返る場合は、DSM コントロールパネルでアカウントに適切な権限を付与する必要がある。

能力境界（File Station API の範囲外）

以下の機能は公式 File Station API には存在せず、本 MCP では提供できません：

• ACL 権限管理：DSM コントロールパネルの機能（SYNO.Core.* プライベートAPI、公開 File Station API ではない）。

• 共有フォルダ AES 暗号化：DSM ストレージ管理の機能（暗号化共有フォルダの作成/マウント）。

• 改ざん防止（読み取り専用/削除不可マーク）：File Station API に設定エントリなし。共有フォルダの読み取り専用マウントで間接的に実現可能。

• ネットワークごみ箱：削除動作は各共有フォルダのごみ箱設定に自動的に従う（有効化済みの場合、削除されたファイルは <share>/#recycle に移動）。API による個別制御は不要であり、不可能でもある。

ディレクトリ構造

src/
  index.js    stdio 入口（本地模式）
  http.js     HTTP 入口（远程模式，Streamable HTTP + 多用户会话池）
  server.js   共享的 MCP Server 构建（注册全部工具）
  env.js      .env 加载
  client.js   Synology API 客户端：API 发现、认证、请求封装、错误码映射
  tools/      每个 File Station API 一个工具模块
test/
  smoke.mjs      对真实 NAS 的全链路冒烟测试（stdio 层逻辑）
  http-smoke.mjs HTTP 模式自测（鉴权、会话、工具调用、会话关闭）
  extended.mjs   扩展能力测试（多格式、批量、解压、回收站）