synology-mcp
Provides tools for interacting with a Synology NAS running DSM 7, including browsing and organizing files via File Station, working with Synology Drive files and labels, managing Download Station downloads, and checking NAS system status such as disks, volumes, health, updates, notifications, and logs. Read-only by default, with optional write operations for file management and downloads.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@synology-mcp ¿Cómo está el NAS? ¿Algún disco con problemas?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
En Panel de control → Usuario y grupo, crea un usuario específico, por ejemplo
claude, sin permisos de administrador.En Permisos, dale acceso de lectura (o lectura y escritura) solo a las carpetas compartidas que quieras que Claude vea.
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-deviceLuego 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-mcpAl 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-mcpPara 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 |
| NAS URL | — | URL de DSM con puerto: |
| DSM user | — | Usuario de DSM |
| DSM password | — | Contraseña |
| Read-only |
|
|
| Accept an invalid HTTPS certificate |
| Acepta un certificado HTTPS autofirmado o caducado (solo en una red de confianza) |
| 2FA device token | — | Token de |
| — |
| Nombre con el que se registró el dispositivo |
| — |
| Cuánto espera una herramienta a una tarea larga antes de devolver su |
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 |
| Hostname, si el usuario es admin, soporte de enlaces compartidos |
| Carpetas compartidas con espacio libre/total |
| Contenido de una carpeta (paginación, orden, filtro glob) |
| Detalles de uno o varios ficheros |
| Búsqueda recursiva por nombre, extensión, tamaño, fecha, propietario |
| Tamaño total, nº de ficheros y carpetas |
| MD5 de un fichero |
| Devuelve el contenido de un fichero de texto o una imagen (límite 1 MB por defecto) |
| Descarga al ordenador local (varios ficheros o carpetas → ZIP) |
| Enlaces públicos creados |
| Tareas de copia/borrado/compresión en curso |
| Progreso de una tarea que no terminó dentro del timeout |
Escritura (solo con SYNOLOGY_READ_ONLY=false)
Herramienta | Qué hace |
| Crear carpeta |
| Renombrar |
| Copiar o mover |
| Borrar (recursivo) |
| Subir un fichero local |
| Crear/reemplazar un fichero de texto |
| Comprimir en ZIP/7z / extraer archivos |
| Gestionar enlaces públicos |
Las rutas del NAS empiezan siempre por una carpeta compartida: /photo/2024/foto.jpg.
Estado del NAS
Herramienta | Qué hace |
| Modelo, versión de DSM, RAM, temperatura, uptime (no requiere admin) |
| CPU, RAM, red y E/S de discos en vivo (requiere admin) |
| Grupos de almacenamiento, volúmenes (espacio libre, avisos) y salud de los discos (requiere admin) |
| SMART de cada disco: sectores defectuosos y su tendencia, horas encendido, temperatura, atributos que fallan (requiere admin) |
| Actualización de DSM disponible (y si es de seguridad) y paquetes con versión nueva (requiere admin) |
| Notificaciones de DSM: errores, avisos, descargas terminadas… (requiere admin) |
| 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 |
| Listar una carpeta de Drive / detalles de un elemento |
| Recientes / con estrella |
| Compartido conmigo / por mí |
| Búsqueda por nombre, contenido, tipo, etiqueta, tamaño, fecha |
| Etiquetas / elementos con una etiqueta |
| Quién tiene acceso a un elemento |
| Carpetas de equipo |
| Poner o quitar estrella |
| Añadir/quitar etiquetas por nombre (crea las que falten) |
| Crear / borrar etiquetas |
| Convertir Word/Excel/PowerPoint/CSV a Synology Office |
Download Station (destinos como rutas del NAS: /home/Descargas)
Herramienta | Qué hace |
| Versión, destino por defecto, límites y velocidad actual |
| Descargas con estado, progreso y velocidad; filtro por estado, tipo o texto |
| Detalle de una descarga: origen, ficheros, pares, trackers |
| Añadir descargas por URL, enlace magnet o fichero |
| Pausar / reanudar |
| Quitar descargas (conserva lo ya descargado) |
| 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 DesktopDesarrollo
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 realVer 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 toolscheck_updatesAvailable DSM and package updatesARead-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 computerARead-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 detailsBRead-only
Full details of download tasks: source URL, owner, peers, files inside a torrent and trackers.
Inputs: ids (required).
downloads_infoDownload Station: status and settingsBRead-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 downloadsARead-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 detailsARead-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 folderBRead-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 labelARead-only
Files and folders that carry a given label (label_id from drive_list_labels).
Inputs: label_id (required).
drive_list_labelsDrive: list labelsBRead-only
The user's Synology Drive labels with their IDs and colors.
Inputs: no named parameters.
drive_list_permissionsDrive: sharing permissionsCRead-only
Who has access to a Drive file or folder and with which role.
Inputs: path (required).
drive_list_team_foldersDrive: team foldersARead-only
Team folders the user can access. Browse them with drive_list and path /team-folders/.
Inputs: no named parameters.
drive_recentDrive: recent filesCRead-only
Files and folders the user used recently in Synology Drive.
Inputs: limit.
drive_searchDrive: searchARead-only
Search Synology Drive by name/content keyword, type, location, labels, owner, size or date. Newly added files can take a few seconds to be indexed.
Inputs: limit, owner, offset, keyword, +8 more.
drive_starredDrive: starred filesCRead-only
Files and folders the user marked with a star in Synology Drive.
Inputs: limit, offset, sort_by, sort_direction.
get_dir_sizeFolder sizeBRead-only
Calculate total size, number of files and number of folders for one or more paths.
Inputs: paths (required).
get_disk_healthDisk health (SMART)ARead-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 infoBRead-only
Get details (size, dates, owner, real path on the volume) for one or more files/folders.
Inputs: paths (required).
get_infoFile Station infoARead-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 MD5CRead-only
Calculate the MD5 checksum of a file on the NAS.
Inputs: path (required).
get_notificationsDSM notificationsARead-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 healthARead-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 infoARead-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)ARead-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 usageARead-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 statusBRead-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 tasksARead-only
List File Station background tasks (copy, move, delete, compress, extract) and their progress.
Inputs: no named parameters.
list_filesList folder contentsARead-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_sharing_linksList sharing linksCRead-only
List the public sharing links created by the user.
Inputs: limit, offset.
read_fileRead fileARead-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 filesARead-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
Scored across 33 tools
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.
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'.
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.
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
Related MCP Connectors
Give Claude only the Google Drive files you choose. Every action logged.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Safe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to manage Synology NAS devices with file operations (create, delete, move, search) and Download Station control through secure authentication and session management.144 PyPI254MIT
- AlicenseNot gradedqualityDmaintenanceConnects 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.4MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseBqualityCmaintenanceEnables 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.16MIT