Skip to main content
Glama
synology-mcp
by r03eRt

synology-mcp

Usa tu NAS Synology desde Claude. Puedes buscar, leer y organizar ficheros, usar Synology Drive, gestionar Download Station (URLs, enlaces magnet y ficheros .torrent) y revisar el estado del NAS (temperatura, discos, volúmenes).

Es un servidor MCP para DSM 7 (probado en DSM 7.4.1). Viene como plugin de Claude Code, como extensión de Claude Desktop o como paquete npm. Arranca en solo lectura: Claude no puede cambiar nada hasta que actives la escritura.

Proyecto independiente, sin relación con Synology Inc.

1. Prepara un usuario en DSM

Claude solo puede hacer lo que permita el usuario de DSM que configures, así que esa es la principal barrera de seguridad. Recomendado:

  1. En Panel de control → Usuario y grupo, crea un usuario específico, por ejemplo claude, sin permisos de administrador.

  2. En Permisos, dale acceso de lectura (o lectura y escritura) solo a las carpetas compartidas que quieras que Claude vea.

  3. En Aplicaciones, permítele File Station y, si los vas a usar, Synology Drive y Download Station.

Con un usuario normal funciona todo salvo las herramientas de estado y salud del NAS (get_system_utilization, get_storage_status, get_disk_health, check_updates, get_notifications y get_system_logs), que necesitan un administrador.

Cuenta con verificación en dos pasos (2FA): ejecuta esto una vez para registrar Claude como dispositivo de confianza. Te pedirá el código del autenticador:

SYNOLOGY_URL=http://192.168.1.10:5000 SYNOLOGY_USERNAME=claude SYNOLOGY_PASSWORD='…' npx synology-mcp register-device

Luego pon el SYNOLOGY_DEVICE_ID que imprime en la configuración (campo «2FA device token»).

Related MCP server: Seafile MCP Server

2. Instala

Claude Code (plugin)

claude plugin marketplace add r03eRt/synology-mcp
claude plugin install synology@synology-mcp

Al activarlo te pide la URL del NAS, el usuario y la contraseña. La contraseña se guarda en el almacén de credenciales del sistema. El plugin incluye el servidor y una skill que enseña a Claude a usar el NAS con cuidado: rutas, qué herramienta usar y confirmar antes de borrar. Hace falta Node.js 22.19 o superior.

Claude Desktop (extensión)

Descarga synology-mcp-<versión>.mcpb de la página de Releases y ábrelo con doble clic. Claude Desktop te pedirá los mismos datos y guardará la contraseña en el llavero.

Cualquier cliente MCP (npm)

{
  "mcpServers": {
    "synology": {
      "command": "npx",
      "args": ["-y", "synology-mcp"],
      "env": {
        "SYNOLOGY_URL": "http://192.168.1.10:5000",
        "SYNOLOGY_USERNAME": "claude",
        "SYNOLOGY_PASSWORD": "…"
      }
    }
  }
}

En Claude Code, sin plugin:

claude mcp add synology -s user -e SYNOLOGY_URL=http://192.168.1.10:5000 -e SYNOLOGY_USERNAME=claude -e SYNOLOGY_PASSWORD='…' -- npx -y synology-mcp

Para no dejar la contraseña en la configuración del cliente, guárdala en un fichero .env con permisos 600 y arranca con node --env-file=/ruta/.env …. Ver docs/configuracion.md.

3. Configuración

Variable

Campo del plugin / extensión

Por defecto

Descripción

SYNOLOGY_URL

NAS URL

—

URL de DSM con puerto: http://IP:5000 o https://nombre:5001

SYNOLOGY_USERNAME

DSM user

—

Usuario de DSM

SYNOLOGY_PASSWORD

DSM password

—

Contraseña

SYNOLOGY_READ_ONLY

Read-only

true

false permite crear, mover, borrar y añadir descargas

SYNOLOGY_INSECURE_TLS

Accept an invalid HTTPS certificate

false

Acepta un certificado HTTPS autofirmado o caducado (solo en una red de confianza)

SYNOLOGY_DEVICE_ID

2FA device token

—

Token de register-device para cuentas con 2FA

SYNOLOGY_DEVICE_NAME

—

synology-mcp

Nombre con el que se registró el dispositivo

SYNOLOGY_TASK_TIMEOUT_MS

—

60000

Cuánto espera una herramienta a una tarea larga antes de devolver su taskid

4. Pídele cosas a Claude

  • «¿Cómo está el NAS? ¿Algún disco con problemas?»

  • «¿Hay actualizaciones pendientes? ¿Qué errores ha habido esta semana?»

  • «Busca los PDF de facturas de 2024 en /home y dime cuánto ocupan.»

  • «¿Qué carpetas ocupan más en /video?»

  • «Lee /home/notas/lista.txt y resúmela.»

  • «Añade este magnet a Download Station en /home/Descargas.»

  • «¿Qué descargas tienen error?»

  • «Crea un enlace para compartir /photo/Viaje que caduque el domingo.»

  • «Lista lo que tengo marcado con estrella en Drive.»

Con la escritura activada, Claude pide confirmación antes de borrar o sobrescribir (lo indica la skill y las herramientas van marcadas como destructivas).

Herramientas

Lectura

Herramienta

Qué hace

get_info

Hostname, si el usuario es admin, soporte de enlaces compartidos

list_shares

Carpetas compartidas con espacio libre/total

list_files

Contenido de una carpeta (paginación, orden, filtro glob)

get_file_info

Detalles de uno o varios ficheros

search_files

Búsqueda recursiva por nombre, extensión, tamaño, fecha, propietario

get_dir_size

Tamaño total, nº de ficheros y carpetas

get_md5

MD5 de un fichero

read_file

Devuelve el contenido de un fichero de texto o una imagen (límite 1 MB por defecto)

download_file

Descarga al ordenador local (varios ficheros o carpetas → ZIP)

list_sharing_links

Enlaces públicos creados

list_background_tasks

Tareas de copia/borrado/compresión en curso

get_task_status

Progreso de una tarea que no terminó dentro del timeout

Escritura (solo con SYNOLOGY_READ_ONLY=false)

Herramienta

Qué hace

create_folder

Crear carpeta

rename

Renombrar

copy_move

Copiar o mover

delete

Borrar (recursivo)

upload_file

Subir un fichero local

write_text_file

Crear/reemplazar un fichero de texto

compress / extract

Comprimir en ZIP/7z / extraer archivos

create_sharing_link / delete_sharing_links

Gestionar enlaces públicos

Las rutas del NAS empiezan siempre por una carpeta compartida: /photo/2024/foto.jpg.

Estado del NAS

Herramienta

Qué hace

get_system_info

Modelo, versión de DSM, RAM, temperatura, uptime (no requiere admin)

get_system_utilization

CPU, RAM, red y E/S de discos en vivo (requiere admin)

get_storage_status

Grupos de almacenamiento, volúmenes (espacio libre, avisos) y salud de los discos (requiere admin)

get_disk_health

SMART de cada disco: sectores defectuosos y su tendencia, horas encendido, temperatura, atributos que fallan (requiere admin)

check_updates

Actualización de DSM disponible (y si es de seguridad) y paquetes con versión nueva (requiere admin)

get_notifications

Notificaciones de DSM: errores, avisos, descargas terminadas… (requiere admin)

get_system_logs

Registros del sistema o de conexiones, con filtros por nivel, texto y fecha (requiere admin)

Synology Drive (rutas /mydrive/... = /home/Drive, /team-folders/<nombre>/... o id:<file_id>)

Herramienta

Qué hace

drive_list / drive_get_info

Listar una carpeta de Drive / detalles de un elemento

drive_recent / drive_starred

Recientes / con estrella

drive_shared_with_me / drive_shared_with_others

Compartido conmigo / por mí

drive_search

Búsqueda por nombre, contenido, tipo, etiqueta, tamaño, fecha

drive_list_labels / drive_list_labelled

Etiquetas / elementos con una etiqueta

drive_list_permissions

Quién tiene acceso a un elemento

drive_list_team_folders

Carpetas de equipo

drive_star (escritura)

Poner o quitar estrella

drive_label (escritura)

Añadir/quitar etiquetas por nombre (crea las que falten)

drive_create_label / drive_delete_label (escritura)

Crear / borrar etiquetas

drive_convert_to_office (escritura)

Convertir Word/Excel/PowerPoint/CSV a Synology Office

Download Station (destinos como rutas del NAS: /home/Descargas)

Herramienta

Qué hace

downloads_info

Versión, destino por defecto, límites y velocidad actual

downloads_list

Descargas con estado, progreso y velocidad; filtro por estado, tipo o texto

downloads_get

Detalle de una descarga: origen, ficheros, pares, trackers

downloads_add (escritura)

Añadir descargas por URL, enlace magnet o fichero .torrent de este ordenador

downloads_pause / downloads_resume (escritura)

Pausar / reanudar

downloads_delete (escritura)

Quitar descargas (conserva lo ya descargado)

downloads_set_destination (escritura)

Cambiar la carpeta de destino de una descarga

Autenticación

El servidor inicia sesión igual que la página web de DSM 7.2. Primero obtiene la clave del servidor con SYNO.API.Auth.Type (cookie _SSID). Después hace un handshake Noise_IK_25519_ChaChaPoly_BLAKE2b y envía un login SYNO.API.Auth versión 7 con ik_message. Todas las peticiones llevan el token X-SYNO-TOKEN.

Es necesario porque DSM 7.2 rechaza algunas operaciones, como Compress, a las sesiones creadas con el login clásico v6: devuelve el error 105 incluso a administradores. Si el NAS no soporta este login, se usa automáticamente el v6.

Cuentas con verificación en dos pasos: ejecutar una vez synology-mcp register-device (pide el código del autenticador) y añadir el SYNOLOGY_DEVICE_ID que imprime. Ver docs/configuracion.md.

Estructura

src/
  index.ts                 arranque del servidor MCP (stdio) y comando register-device
  server.ts                creación del servidor y registro de herramientas
  config.ts                variables de entorno
  synology/client.ts       login, descubrimiento de APIs, peticiones, subida/descarga, polling
  synology/errors.ts       códigos de error de la guía oficial
  synology/noise.ts        handshake Noise del login de DSM 7.2
  tools/filestation.ts     herramientas MCP de File Station
  tools/system.ts          get_system_info, get_system_utilization, get_storage_status
  tools/health.ts          get_disk_health, check_updates, get_notifications, get_system_logs
  tools/drive.ts           herramientas de Synology Drive
  tools/downloadstation.ts herramientas de Download Station
  tools/format.ts          formateo de respuestas
test/                      pruebas (ver docs/pruebas.md)
plugin/                    plugin de Claude Code: manifiesto, skill synology-nas y servidor en un fichero
.claude-plugin/            marketplace (para `claude plugin marketplace add`)
mcpb/manifest.json         manifiesto de la extensión de Claude Desktop

Desarrollo

npm install
npm run build        # dist/ (paquete npm)
npm run bundle       # plugin/server/synology-mcp.cjs: servidor en un solo fichero para el plugin y la extensión
npm run pack:mcpb    # build/synology-mcp-<versión>.mcpb
npm test             # genera el bundle y ejecuta 76 pruebas con un NAS simulado, sin red
SYNOLOGY_ENV_FILE=.env.admin npm run test:real  # opcional, contra un NAS real

Ver docs/distribucion.md para el empaquetado y la publicación.

Pendiente

  • QuickConnect: SynologyClient.baseUrl() es el punto donde resolver un ID de QuickConnect a una dirección.

Available Tools

33 tools
check_updatesAvailable DSM and package updatesA
Read-only

Whether a DSM update is available (version, whether it is a security update and whether it needs a reboot) and which installed packages have a newer version in the Package Center. Only checks; installs nothing. Needs a DSM administrator account.

Inputs: no named parameters.

download_fileDownload to this computerA
Read-only

Download files/folders from the NAS to a local path on this computer. Several paths (or a folder) are downloaded as a single ZIP.

Inputs: paths (required), local_path (required), overwrite.

downloads_getDownload Station: task detailsB
Read-only

Full details of download tasks: source URL, owner, peers, files inside a torrent and trackers.

Inputs: ids (required).

downloads_infoDownload Station: status and settingsB
Read-only

Download Station version, whether the user manages it, default destination folder, speed limits and the current total download/upload speed.

Inputs: no named parameters.

downloads_listDownload Station: list downloadsA
Read-only

List download tasks with status, progress, size, speeds and destination. Filter by status, type or text in the title. Also returns how many tasks there are in each status.

Inputs: type, limit, query, offset, +1 more.

drive_get_infoDrive: file detailsA
Read-only

Details of one Drive file or folder: size, owner, labels, star, sharing state, file_id and permanent link.

Inputs: path (required).

drive_listDrive: list folderB
Read-only

List a Synology Drive folder (My Drive or a team folder). Use drive_list_team_folders to find team folders.

Inputs: path, limit, offset, sort_by, +1 more.

drive_list_labelledDrive: files with a labelA
Read-only

Files and folders that carry a given label (label_id from drive_list_labels).

Inputs: label_id (required).

drive_list_labelsDrive: list labelsB
Read-only

The user's Synology Drive labels with their IDs and colors.

Inputs: no named parameters.

drive_list_permissionsDrive: sharing permissionsC
Read-only

Who has access to a Drive file or folder and with which role.

Inputs: path (required).

drive_list_team_foldersDrive: team foldersA
Read-only

Team folders the user can access. Browse them with drive_list and path /team-folders/.

Inputs: no named parameters.

drive_recentDrive: recent filesC
Read-only

Files and folders the user used recently in Synology Drive.

Inputs: limit.

drive_shared_with_meDrive: shared with meC
Read-only

Files and folders other users shared with the logged-in user.

Inputs: limit, offset, sort_by, sort_direction.

drive_shared_with_othersDrive: shared with othersB
Read-only

Files and folders of the user (My Drive or team folders) that are shared with other people.

Inputs: limit, offset, sort_by, sort_direction.

drive_starredDrive: starred filesC
Read-only

Files and folders the user marked with a star in Synology Drive.

Inputs: limit, offset, sort_by, sort_direction.

get_dir_sizeFolder sizeB
Read-only

Calculate total size, number of files and number of folders for one or more paths.

Inputs: paths (required).

get_disk_healthDisk health (SMART)A
Read-only

Per-disk health from Storage Manager: overall status, SMART status and last test, bad sectors (and whether they are growing), power-on hours, remaining life, temperature and the SMART attributes that matter (or all of them). Needs a DSM administrator account. Serial numbers are never returned.

Inputs: disk, all_attributes.

get_file_infoGet file infoB
Read-only

Get details (size, dates, owner, real path on the volume) for one or more files/folders.

Inputs: paths (required).

get_infoFile Station infoA
Read-only

Get File Station info for the logged-in user: hostname, whether it is an admin, and sharing support.

Inputs: no named parameters.

get_md5File MD5C
Read-only

Calculate the MD5 checksum of a file on the NAS.

Inputs: path (required).

get_notificationsDSM notificationsA
Read-only

Recent notifications from the DSM desktop (the bell): errors, warnings and events such as finished downloads, failed backups, disk warnings or failed certificate renewals. Each has its time, level, event name and parameters. Needs a DSM administrator account.

Inputs: level, limit.

get_storage_statusNAS storage healthA
Read-only

Storage pools (RAID type, status, member disks), volumes (filesystem, used/free space, status and warnings such as fs_almost_full) and internal disks (model, size, temperature, SMART status, bad sectors). Serial numbers are not returned. Needs a DSM administrator account.

Inputs: no named parameters.

get_system_infoNAS system infoA
Read-only

Basic NAS status: model, DSM version, RAM, temperature (and whether it is in warning), uptime, NAS clock and which packages used by these tools (Synology Drive, Download Station, Photos) are installed. Works without admin rights.

Inputs: no named parameters.

get_system_logsNAS logs (Log Center)A
Read-only

Entries from the NAS's own logs (Log Center): 'system' (services, certificates, disks, updates…) or 'connection' (sign-ins, failed logins, by user and IP). Filter by level, text and dates. Newest first. Needs a DSM administrator account.

Inputs: to, from, type, level, +3 more.

get_system_utilizationNAS live resource usageA
Read-only

Live CPU (% and load average), memory (RAM and swap), network throughput and per-disk / per-volume I/O. Needs a DSM administrator account; normal users get an explanatory error.

Inputs: no named parameters.

get_task_statusTask statusB
Read-only

Check progress of a background task that was still running when a previous tool returned its task id.

Inputs: taskid (required), task_type (required).

list_background_tasksList background tasksA
Read-only

List File Station background tasks (copy, move, delete, compress, extract) and their progress.

Inputs: no named parameters.

list_filesList folder contentsA
Read-only

List files and folders inside a NAS folder. Supports paging, sorting, glob filtering and file type filtering.

Inputs: folder_path (required), limit, offset, pattern, +3 more.

list_sharesList shared foldersA
Read-only

List the shared folders (top-level roots such as /photo, /video, /home) with free/total space.

Inputs: only_writable.

read_fileRead fileA
Read-only

Read a file from the NAS and return its content: text files as text, images (png/jpg/gif/webp) as an image. Refuses files larger than max_bytes.

Inputs: path (required), max_bytes.

search_filesSearch filesA
Read-only

Search recursively for files/folders by name pattern, extension, size, date or owner. Waits for the search to finish (up to the task timeout) and returns matches.

Inputs: folder_paths (required), limit, owner, pattern, +7 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 33 tools

    Disambiguation4/5

    Tools are partitioned by subsystem (File Station, system/storage, Synology Drive, Download Station) with distinct descriptions, so overlaps like list_files vs drive_list vs list_shares are resolvable. Minor confusion remains: bare 'get_info' (File Station user info) sits next to 'get_system_info', and drive_list_labels vs drive_list_labelled are near-homonyms. Overall mostly distinct with a couple of easily-mistaken pairs.

    Naming Consistency4/5

    Consistent snake_case verb_noun pattern dominates: list_files, get_file_info, search_files, get_disk_health, drive_search, downloads_list. Deviations are minor: differing prefix conventions (drive_ singular vs downloads_ plural), noun-number inconsistency (list_files vs get_info/get_md5), and the vague bare 'get_info'.

    Tool Count3/5

    33 tools is heavy for a single server, though it legitimately spans four distinct subsystems (files, system health, Drive, Download Station). Each tool does earn a place individually, but the surface is large enough that an agent must scan many similar-sounding entries. Borderline over-scoped rather than bloated with filler.

    Completeness3/5

    Read/query coverage is thorough, but the surface is essentially read-only: no upload, create folder, copy/move/delete/rename, or share-link creation, even though background tasks for those operations are listed. Download Station is likewise read-only (info/list/get but no add, pause, or remove task). Agents asked to modify anything will hit a dead end.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects Claude to your self-hosted or cloud-based Seafile storage for managing libraries and files through natural language. It enables users to browse directories, read file contents, and perform file operations like moving, renaming, or searching across their private infrastructure.
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to manage files on Synology NAS via the File Station API, supporting operations like browsing, searching, uploading/downloading, creating, renaming, copying, moving, deleting, compressing, and extracting.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to query a Synology NAS through MCP for system health, storage, network, packages, power, Cloud Sync, scheduled tasks, logs, notifications, and files, with read-only access by default and optional write permission for Cloud Sync controls.
      16
      MIT