Skip to main content
Glama
synology-filestation-mcp

synology-filestation-mcp

by 01men

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 にコピーして記入し、起動時に自動読み込みも可能):

変数

説明

SYNOLOGY_HOST

DSM アドレス、例:http://192.168.1.1:5000(末尾スラッシュなし)

SYNOLOGY_USER

DSM アカウント

SYNOLOGY_PASSWORD

DSM パスワード

SYNOLOGY_DOWNLOAD_DIR

オプション、fs_download のデフォルトローカル保存ディレクトリ

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認証情報がリクエストヘッダーで平文送信されないように推奨。

ツール一覧

ツール

説明

内部 API

fs_list_shares

共有フォルダ一覧を表示

SYNO.FileStation.List / list_share

fs_list

ディレクトリ内容一覧(ページング、ソート、ワイルドカードフィルタ対応)

SYNO.FileStation.List / list

fs_get_info

ファイル/ディレクトリの詳細情報を取得

SYNO.FileStation.List / getinfo

fs_search

パターンでファイル検索(自動ポーリングで完了まで待機)

SYNO.FileStation.Search / start+list

fs_search_stop

検索タスクを停止

SYNO.FileStation.Search / stop

fs_search_clean

すべての検索タスクをクリア

SYNO.FileStation.Search / clean

fs_create_folder

フォルダを作成

SYNO.FileStation.CreateFolder / create

fs_rename

ファイル/フォルダの名前を変更

SYNO.FileStation.Rename / rename

fs_copy_move

コピー/移動(非同期タスク、taskid を返す)

SYNO.FileStation.CopyMove / start

fs_task_status

バックグラウンドタスクの進捗を照会

SYNO.FileStation.BackgroundTask / list

fs_delete

削除(非同期タスク、復元不可)

SYNO.FileStation.Delete / start

fs_download

NAS ファイルをローカルディレクトリにダウンロード

SYNO.FileStation.Download / download

fs_upload

ローカルファイルを NAS にアップロード

SYNO.FileStation.Upload / upload

fs_compress

NAS 上で zip/7z に圧縮(非同期タスク)

SYNO.FileStation.Compress / start

fs_extract

NAS 上で解凍(非同期タスク、対象ディレクトリは事前に存在が必要)

SYNO.FileStation.Extract / start

テスト

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   扩展能力测试(多格式、批量、解压、回收站)

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides secure file system operations for AI assistants including directory listing, file reading/writing, deletion, searching, and copying. Features safety controls like path validation, permission checks, and file size limits.
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to perform FTP/FTPS/SFTP file operations including upload, download, sync, and directory management with multi-server support.
      36
      107 npm
      8
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      MCP server enabling AI agents to manage and monitor Synology NAS via official DSM API, including file operations, system stats, backups, downloads, and camera lists.
      15
      -