synology-filestation-mcp

Сервис MCP (Model Context Protocol), обернутый поверх Synology File Station Web API, позволяющий AI Agent напрямую управлять файлами на Synology NAS: просматривать каталоги, искать, загружать/скачивать, создавать/переименовывать/копировать/перемещать/удалять, архивировать/распаковывать и т.д.

Поддерживает два режима работы:

• stdio, локальный режим (src/index.js): запускается на персональном компьютере, учетные данные берутся из локальных переменных окружения

• Streamable HTTP, удаленный режим (src/http.js): централизованное развертывание на сервере, используется несколькими пользователями, каждый передает свои учетные данные NAS через заголовки запроса

Требования к окружению

• Node.js >= 18 (разработка проверена на Node 24; для серверов с низкой версией glibc доступна сборка glibc-217 на unofficial-builds)

• 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>

• Управление сеансами: автоматическая очистка и выход из NAS после 30 минут простоя (настраивается через 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).

• Параметр additional у SYNO.FileStation.List v2 требует формат JSON-массива (например, ["size","time"]), строка, разделенная запятыми, будет молча проигнорирована.

• Для запроса информации о файлах используется SYNO.FileStation.List / getinfo (SYNO.FileStation.Info / get возвращает конфигурацию сервера File Station, а не информацию о файлах).

• Загрузка использует версию API 2: на практике в v3 параметр overwrite не работает, при совпадении имен файлов возвращается 414. При загрузке sid передается двойным каналом: через поле формы и через Cookie: id=<sid>.

• Копирование/перемещение/удаление являются асинхронными задачами; SYNO.FileStation.BackgroundTask в DSM 7.x имеет только метод 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.

Границы возможностей (не входят в API File Station)

Следующие возможности отсутствуют в официальном API File Station, и данный MCP не может их предоставить:

• Управление правами ACL: относится к функциям панели управления DSM (частные интерфейсы SYNO.Core.*, не публичный API File Station).

• AES-шифрование общих папок: относится к функциям управления хранилищем DSM (создание/монтирование зашифрованных общих папок).

• Защита от изменений (флаги только для чтения / запрета удаления): API File Station не имеет точки входа для установки; может быть косвенно реализовано через монтирование общей папки только для чтения.

• Сетевая корзина: поведение удаления автоматически следует настройкам корзины для каждой общей папки (если включена, удаленные файлы попадают в <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   扩展能力测试（多格式、批量、解压、回收站）