mcp-synology

Servidor MCP para dispositivos Synology NAS. Expone la funcionalidad de la API de Synology DSM como herramientas MCP que Claude puede utilizar.

Migración desde synology-mcp

Si estás actualizando desde synology-mcp (v0.3.x o anterior), el paquete ha sido renombrado. Un script de migración gestiona automáticamente la configuración, el estado, las entradas del llavero y la configuración de Claude Desktop:

# Download and run the migration script
curl -O https://raw.githubusercontent.com/cmeans/mcp-synology/main/scripts/migrate-from-synology-mcp.py
python migrate-from-synology-mcp.py          # dry run — preview changes
python migrate-from-synology-mcp.py --apply  # apply changes

El script migra:

• Directorio de configuración (~/.config/synology-mcp/ → ~/.config/mcp-synology/)

• Directorio de estado (~/.local/state/synology-mcp/ → ~/.local/state/mcp-synology/)

• Credenciales del llavero

• claude_desktop_config.json de Claude Desktop (actualiza el comando y las rutas)

Consulta CHANGELOG.md para obtener todos los detalles sobre los cambios importantes.

Módulos compatibles

File Station

Explora, busca, transfiere y gestiona archivos en tu NAS. 14 herramientas en dos niveles de permisos:

• LECTURA — list_shares, list_files, list_recycle_bin, search_files, get_file_info, get_dir_size, download_file

• ESCRITURA — create_folder, rename, copy_files, move_files, delete_files, restore_from_recycle_bin, upload_file

Sistema

Monitoriza el estado y la utilización de recursos del NAS. 2 herramientas de solo lectura:

• get_system_info — modelo, versión de firmware, RAM, temperatura, tiempo de actividad (funciona para todos los usuarios)

• get_resource_usage — carga de CPU en tiempo real, uso de memoria, E/S de disco, rendimiento de red (requiere cuenta de administrador)

Características

• Configuración interactiva — configuración guiada que crea tu archivo de configuración, almacena credenciales, gestiona 2FA y genera un fragmento para Claude Desktop

• Niveles de permisos — LECTURA o ESCRITURA por módulo, aplicados en el registro de la herramienta

• Soporte 2FA — detección automática; arranque de token de dispositivo con reautenticación silenciosa automática

• Credenciales seguras — integración con el llavero del SO que funciona de forma transparente en macOS, Windows y Linux (incluido desde Claude Desktop). Consulta docs/credentials.md.

• Multi-NAS — gestiona múltiples dispositivos NAS con configuraciones, credenciales y estados separados

Inicio rápido

1. Ejecutar la configuración

uvx mcp-synology setup

Requiere uv. uvx descarga y ejecuta la última versión automáticamente; no se necesita ningún paso de instalación por separado.

La configuración solicitará el host de tu NAS, las credenciales y tus preferencias. Si tu cuenta tiene activada la autenticación 2FA, solicitará un código OTP y almacenará un token de dispositivo para futuros inicios de sesión automáticos.

Al finalizar, imprimirá un fragmento JSON de Claude Desktop listo para copiar y pegar.

2. Añadir a Claude Desktop

Copia el fragmento de la configuración en tu claude_desktop_config.json y reinicia Claude Desktop. Se verá algo así:

{
  "mcpServers": {
    "synology-nas": {
      "command": "uvx",
      "args": ["mcp-synology", "serve", "--config", "~/.config/mcp-synology/nas.yaml"]
    }
  }
}

El nombre del archivo de configuración (por ejemplo, nas.yaml) también sirve como identificador natural para la conexión; puedes nombrarlo para que coincida con tu NAS (por ejemplo, home-nas.yaml, office-nas.yaml).

En Linux, el servidor detecta automáticamente el socket de sesión D-Bus para el acceso al llavero. Si la detección automática falla, añade "env": {"DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/<uid>/bus"} a la configuración de Claude Desktop. El comando de configuración incluye esto en el fragmento generado.

3. Verificar

uvx mcp-synology check                # Validates credentials work
uvx mcp-synology setup --list         # Shows all configured NAS instances

Alternativa: instalación global

Si prefieres una instalación persistente (evita la descarga en cada invocación):

uv tool install mcp-synology
mcp-synology setup
mcp-synology check

Alternativa: modo solo variables de entorno

No se necesita archivo de configuración si SYNOLOGY_HOST está definido. Esto es útil para entornos Docker o CI:

{
  "mcpServers": {
    "synology": {
      "command": "uvx",
      "args": ["mcp-synology", "serve"],
      "env": {
        "SYNOLOGY_HOST": "192.168.1.100",
        "SYNOLOGY_USERNAME": "your_user",
        "SYNOLOGY_PASSWORD": "your_password"
      }
    }
  }
}

O desde la CLI:

SYNOLOGY_HOST=192.168.1.100 uvx mcp-synology check

Soporte 2FA

mcp-synology es totalmente compatible con cuentas DSM con autenticación de dos factores. Se detecta automáticamente; no necesitas configurar nada especial:

1. Arranque — mcp-synology setup detecta 2FA, solicita tu código OTP y almacena un token de dispositivo en el llavero

2. Reautenticación silenciosa — los inicios de sesión posteriores utilizan el token de dispositivo automáticamente (sin solicitudes de OTP)

3. Por instancia — cada configuración de NAS obtiene su propio token de dispositivo, por lo que las configuraciones mixtas con/sin 2FA funcionan bien

Los tokens de dispositivo persisten hasta que los revoques explícitamente en DSM (Personal > Seguridad > Actividad de inicio de sesión). No caducan por sí solos. Si un token es revocado, ejecuta mcp-synology setup de nuevo para volver a realizar el arranque.

Llavero y credenciales

Las credenciales se almacenan en el llavero del SO y se accede a ellas de forma transparente:

Orden de resolución de credenciales: variables de entorno > archivo de configuración > llavero. Las fuentes explícitas anulan el valor predeterminado implícito.

Para entornos sin llavero (Docker, CI), utiliza variables de entorno o credenciales en línea en el archivo de configuración.

Consulta docs/credentials.md para conocer los nombres de los servicios de llavero, la configuración multi-NAS y cómo inspeccionar/eliminar credenciales almacenadas.

Actualizaciones

mcp-synology busca actualizaciones y te notifica en tu conversación de Claude Desktop; la primera respuesta de la herramienta en cada sesión incluirá un aviso si hay una versión más reciente disponible en PyPI.

Para gestionar las actualizaciones desde la CLI:

mcp-synology --check-update                 # Check for a newer version
mcp-synology --auto-upgrade enable           # Auto-upgrade on each interactive run
mcp-synology --revert                        # Roll back to previous version
mcp-synology --revert 0.1.0                  # Roll back to a specific version

Para desactivar las notificaciones de actualización, añade esto a tu configuración (nivel superior):

# ~/.config/mcp-synology/config.yaml
check_for_updates: false

Configuración

La configuración interactiva crea un archivo de configuración para ti. Para una configuración manual u opciones avanzadas, consulta examples/:

• config-minimal.yaml — la configuración más simple posible

• config-power-user.yaml — HTTPS, tiempos de espera personalizados, registro, instrucciones

• config-docker.yaml — basada en variables de entorno

Multi-NAS

Cada NAS obtiene su propio archivo de configuración, credenciales y entrada en Claude Desktop. El nombre del archivo de configuración sirve como identificador natural (por ejemplo, home-nas.yaml, media-server.yaml).

Establece alias para darle a Claude un nombre para mostrar para la conexión:

# ~/.config/mcp-synology/home-nas.yaml
alias: HomeNAS

El alias aparece en el nombre del servidor MCP (por ejemplo, synology-HomeNAS) para que Claude sepa con qué NAS está hablando.

Instrucciones personalizadas

Las instrucciones personalizadas te permiten dar forma a cómo interactúa Claude con tus herramientas NAS. Esto es útil cuando:

• Múltiples conexiones NAS — dile a Claude qué conexión preferir para diferentes tareas ("usa esto para multimedia, usa admin para operaciones entre usuarios")

• Barreras de seguridad — añade reglas como "confirma siempre antes de borrar" o "nunca toques /Backups"

• Contexto — explica qué hay en el NAS ("este es un servidor multimedia, /video tiene nuestra biblioteca ordenada por género")

Añadir contexto — custom_instructions se antepone al prompt integrado (mayor prioridad):

# ~/.config/mcp-synology/config.yaml
custom_instructions: |
  This is the admin NAS with elevated privileges.
  Prefer this connection for file operations requiring cross-user access.
  Never delete files from /Backups without explicit confirmation.

Control total — instructions_file reemplaza el prompt integrado por completo. Copia el server.md integrado como punto de partida:

# ~/.config/mcp-synology/config.yaml
instructions_file: ~/.config/mcp-synology/my-instructions.md

Ambos admiten variables de plantilla: {display_name}, {instance_id}, {host}, {port}.

Depuración

Dos formas de activar el registro de depuración:

mcp-synology check --verbose                          # --verbose flag on setup/check
SYNOLOGY_LOG_LEVEL=debug mcp-synology serve           # env var, works for all commands

O establécelo de forma persistente en tu archivo de configuración:

# ~/.config/mcp-synology/config.yaml
logging:
  level: debug
  file: ~/.local/state/mcp-synology/nas/server.log  # optional, logs to stderr by default

La salida de depuración incluye cada solicitud/respuesta de la API de DSM (contraseñas enmascaradas), pasos de resolución de credenciales, descubrimiento de configuración, negociación de versiones y decisiones de registro de módulos.

Contribución

Consulta DEVELOPMENT.md para comandos de compilación, pruebas, configuración de pruebas de integración y documentos de diseño.

Agradecimientos

Este proyecto se construyó utilizando un enfoque de Codificación basada en especificaciones (Spec-First Coding): un modelo de colaboración humano-IA donde el diseño precede a la implementación y las especificaciones son el contrato entre ambos.

A diferencia de la "codificación por vibraciones" (vibe coding), donde describes lo que quieres y dejas que la IA genere código sobre la marcha, la codificación basada en especificaciones trata el diseño como una fase separada y deliberada. Las cuatro especificaciones en docs/specs/ se desarrollaron a través de una conversación extendida: explorando compensaciones, rechazando alternativas y documentando decisiones con justificación. La implementación utilizó entonces las especificaciones como fuente de verdad a lo largo de 11 fases de construcción.

Las pruebas en tiempo real con hardware real revelaron comportamientos que las especificaciones no podían anticipar (peculiaridades de la API de DSM, limitación del servicio de búsqueda, incompatibilidades de formato de versión). Estos descubrimientos están documentados en CLAUDE.md y en el código, que es la autoridad donde las especificaciones divergen.

Licencia

Apache 2.0