synology-filestation-mcp

Servicio MCP (Model Context Protocol) basado en la API web de Synology File Station, que permite a los agentes de IA gestionar directamente archivos en un NAS Synology: navegar directorios, buscar, subir/descargar, crear/renombrar/copiar/mover/eliminar, comprimir/descomprimir, etc.

Admite dos modos de ejecución:

• Modo local stdio (src/index.js): se ejecuta en la computadora personal, las credenciales se colocan en variables de entorno locales.

• Modo remoto HTTP Streamable (src/http.js): se despliega centralizadamente en un servidor, varios usuarios lo comparten, y las credenciales de cada NAS se pasan mediante encabezados de solicitud.

Requisitos del entorno

• Node.js >= 18 (desarrollo verificado con Node 24; servidores con glibc baja pueden usar las compilaciones unofficial-builds para glibc-217)

• DSM 7.x (probado en DSM 7.2)

Related MCP server: Synology MCP Server

Instalación

npm install

Modo 1: Modo local stdio

Proporcione la información de conexión del NAS mediante variables de entorno (también puede copiar .env.example como .env y completarlo, el servicio lo cargará automáticamente al iniciar):

Tomando como ejemplo Claude Desktop, configure 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"
      }
    }
  }
}

Modo 2: Modo HTTP remoto (compartido entre múltiples usuarios)

Inicio del servidor:

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

npm run start:http

Características:

• Multi-usuario: cada sesión MCP mantiene de forma independiente el estado de inicio de sesión del NAS (pool de sid), sin interferencias.

• Transferencia de credenciales: el cliente proporciona su propia cuenta NAS X-NAS-User / X-NAS-Password mediante encabezados de solicitud, y opcionalmente X-NAS-Host para sobrescribir el predeterminado del servidor; si falta, se recurre a las variables de entorno del servidor (admite cuentas unificadas gestionadas por el servidor).

• Autenticación: si se establece MCP_AUTH_TOKEN, todas las solicitudes /mcp deben incluir Authorization: Bearer <token>.

• Gestión de sesiones: las sesiones inactivas durante 30 minutos se limpian automáticamente y cierran sesión en el NAS (SESSION_IDLE_TTL_MS ajustable).

• Verificación de salud: GET /health

Configuración del cliente (compatible con clientes MCP remotos, mediante URL):

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

Ejemplo de despliegue con 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

Consejo de seguridad: en producción, se recomienda usar HTTPS (proxy inverso) para terminar TLS, evitando que las credenciales del NAS viajen en texto claro en los encabezados.

Lista de herramientas

Pruebas

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

La prueba de humo ejecuta un flujo completo contra el NAS: iniciar sesión → listar carpetas compartidas → crear directorio → subir archivo → listar → consultar información → renombrar → copiar → buscar → descargar y verificar contenido → eliminar limpiando → cerrar sesión. La prueba creará un directorio temporal mcp-smoke-test bajo alguna carpeta compartida con permisos de escritura, y lo eliminará automáticamente al finalizar.

También hay una prueba de capacidades extendidas test/extended.mjs (node test/extended.mjs, también lee variables de entorno): cubre la verificación byte por byte de subida/descarga de 23 formatos de archivo (documentos/imágenes/videos/audio/comprimidos/base de datos/imágenes de máquina virtual), copia/movimiento/eliminación masiva, descompresión en el NAS, verificación de ubicación en la papelera de reciclaje, y sondeo de límites de permisos y seguridad.

Notas de implementación (compatibilidad DSM 7.x)

• Al iniciar, primero llama a SYNO.API.Info para descubrir la ruta y versión de cada API; el inicio de sesión usa SYNO.API.Auth (format=sid).

• El parámetro additional de SYNO.FileStation.List v2 requiere formato de array JSON (por ejemplo ["size","time"]); una cadena separada por comas se ignora silenciosamente.

• La consulta de información de archivos usa SYNO.FileStation.List / getinfo (SYNO.FileStation.Info / get devuelve la configuración del servidor File Station, no la información del archivo).

• La subida usa la versión 2 de la API: en la práctica, en v3 el parámetro overwrite no funciona y los archivos con el mismo nombre devuelven 414. El sid se transmite mediante doble canal: campo de formulario y Cookie: id=<sid>.

• Copiar/mover/eliminar son tareas asíncronas; SYNO.FileStation.BackgroundTask en DSM 7.x solo tiene el método list (sin status), se consulta el progreso filtrando por taskid.

• La búsqueda es una tarea asíncrona; la herramienta sondea internamente list hasta que finished.

• El directorio de destino de SYNO.FileStation.Extract debe existir previamente, de lo contrario devuelve 408 (No such file or directory).

• SYNO.FileStation.Compress depende de los permisos de aplicación de la cuenta en DSM; si devuelve 105 (session does not have permission), se deben otorgar los permisos correspondientes a la cuenta en el Panel de control de DSM.

Límites de capacidad (fuera del alcance de la API de File Station)

Las siguientes capacidades no existen en la API oficial de File Station, por lo que este MCP no puede proporcionarlas:

• Gestión de permisos ACL: pertenece a las funciones del Panel de control de DSM (interfaces privadas SYNO.Core.*, no son API pública de File Station).

• Cifrado AES de carpetas compartidas: pertenece a las funciones de gestión de almacenamiento de DSM (crear/montar carpetas compartidas cifradas).

• Marcas de solo lectura/no eliminables: la API de File Station no tiene entrada de configuración; se puede implementar indirectamente montando la carpeta compartida como solo lectura.

• Papelera de reciclaje de red: la acción de eliminación sigue automáticamente la configuración de la papelera de reciclaje de cada carpeta compartida (si está activada, los archivos eliminados van a <share>/#recycle); la API no necesita ni puede controlarlo por separado.

Estructura del directorio

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