mcp-server-synology

An MCP server that exposes a Synology NAS through the official DSM WebAPI.

It covers File Station, Download Station, Synology Photos, Container Manager and DSM system management with purpose-built tools, and reaches everything else through a guarded generic bridge to the raw DSM WebAPI.

Why the generic bridge exists

DSM exposes several hundred APIs and Synology publicly documents only a fraction of them. Shipping one tool per API is neither possible nor useful, so this server takes a two-layer approach:

• Curated tools for the things you actually do every day. They validate input, resolve DSM's asynchronous background tasks, translate numeric error codes into sentences, and enforce the path allowlist.
• list_dsm_apis + call_dsm_api for everything else: Surveillance Station, Hyper Backup, certificates, users and groups, the firewall, Synology Drive, task scheduler, and any API a future DSM version adds.

The bridge is not a privilege escalation. Every call still runs as the DSM account you configured and is bounded by that account's permissions. It is gated behind a separate switch only because it bypasses the path allowlist and the read-only heuristics the curated tools apply.

Tools

File Station — browse and read

Tool	Purpose
list_shared_folders	Discover the shared folders the account can reach
list_files	List a folder with paging, sorting and extension filters
get_file_info	Size, timestamps, owner and permissions for specific items
search_files	Indexed DSM search by name, extension, size or modified time
read_file	Read a text file inline, size-capped and binary-safe
get_folder_size	Recursive size and item count of folders
get_file_checksum	MD5 of a file without downloading it

File Station — write, archive and share

Tool	Purpose
create_folder	Create folders, optionally with parents
write_file	Upload text or base64 content to a file
rename_file	Rename in place
move_files / copy_files	Relocate or duplicate, waiting for completion
delete_files	Permanent delete, separately gated
compress_files	Create a ZIP or 7z archive, optionally encrypted
extract_archive	Extract ZIP, 7z, RAR, TAR or GZ
list_archive_contents	Inspect an archive without extracting it
create_sharing_link	Public link with optional expiry and password
list_sharing_links / delete_sharing_link	Audit and revoke public links

Download Station

Tool	Purpose
list_download_tasks	All tasks with progress and speed
get_download_task	Full detail for specific tasks
create_download_task	Queue HTTP, FTP or magnet downloads
control_download_task	Pause, resume or remove tasks
get_download_station_info	Version, throughput and schedule

Synology Photos

Tool	Purpose
list_photo_albums	Albums in the personal or shared space
list_photos	Photos and videos with EXIF, location and tags
list_photo_folders	Navigate the Photos folder tree
search_photos	Search by subject, place, person or filename

Container Manager

Tool	Purpose
list_containers	Containers with state, CPU and memory
get_container_details	Ports, mounts, environment, network
control_container	Start, stop or restart
list_container_images	Stored images and their size

System

Tool	Purpose
get_system_info	Model, DSM version, serial, uptime, temperature
get_resource_usage	Live CPU, memory, disk I/O and network
get_storage_info	Volumes, disks, free space and SMART health
list_installed_packages	Which DSM packages exist and are running
list_shares_admin	Shared folder configuration and encryption
list_active_connections	Who is connected and over which protocol
control_system_power	Reboot or shut down the NAS

Generic bridge

Tool	Purpose
list_dsm_apis	Discover every API this DSM exposes
call_dsm_api	Invoke any DSM WebAPI method

Security model

The server assumes it is being driven by an AI client, so the defaults are the safe ones and every dangerous capability is opt-in.

Layer 1 — the DSM account. Create a dedicated non-administrator user in DSM and grant it only the shared folders it needs. Nothing this server does can exceed what that account is allowed to do. Never point it at an admin account.

Layer 2 — the policy switches. Independent of DSM permissions:

Setting	Default	Effect
SYNOLOGY_READONLY	true	Every mutating tool is hidden and refused
SYNOLOGY_ALLOW_DELETE	false	Deletion refused even when writes are on
SYNOLOGY_ALLOW_SYSTEM_CONTROL	false	No reboot, shutdown or container control
SYNOLOGY_ALLOW_GENERIC_API	false	call_dsm_api is hidden
SYNOLOGY_ALLOWED_PATHS	empty	Restrict File Station to specific folders
SYNOLOGY_DENIED_PATHS	empty	Always-blocked folders
SYNOLOGY_MAX_READ_BYTES	1048576	Cap on inline file reads

Paths are validated before every File Station call. Traversal segments are rejected outright rather than resolved, because a resolved path can still escape an allowlist through a symlink on the NAS.

Tools that can never succeed under the current policy are hidden from the tool list rather than advertised and then refused, so the model does not keep retrying them.

Layer 3 — the transport. Set SYNOLOGY_MCP_TOKEN and every HTTP client must send Authorization: Bearer <token>.

Suggested rollout

1. Read-only. Defaults as shipped. Confirm the tools see what you expect.
2. Scoped writes. Set SYNOLOGY_READONLY=false and SYNOLOGY_ALLOWED_PATHS to one or two working folders.
3. Operations. Enable delete, system control or the generic bridge only once you trust the setup.

Configuration

Copy .env.example to .env and fill it in. SYNOLOGY_URL, SYNOLOGY_USER and SYNOLOGY_PASSWORD are required; everything else has a safe default.

If DSM uses a self-signed certificate, set SYNOLOGY_INSECURE_TLS=true. This is scoped to this client's connection pool rather than disabling TLS verification for the whole process.

Running

Docker Compose

cp .env.example .env
$EDITOR .env
docker compose up -d --build
docker compose logs -f

The container binds to 127.0.0.1:3020 by default so only a local reverse proxy can reach it. Override with SYNOLOGY_HOST_BIND and SYNOLOGY_HOST_PORT.

Local stdio

npm install
npm run build
SYNOLOGY_MCP_TRANSPORT=stdio node dist/index.js

Reaching a NAS that sits behind your home router

A hosted MCP server cannot dial into a home LAN directly. Rather than port-forwarding DSM to the public internet, put both machines on a private overlay network and point SYNOLOGY_URL at the overlay address:

• Tailscale — install on the NAS and the host running this server, then use the NAS's tailnet address. Simplest option, no router changes.
• WireGuard — a manual tunnel if you already run one.
• frp / Cloudflare Tunnel — a reverse tunnel initiated from the NAS.

Only the MCP server needs to reach DSM. DSM itself stays unexposed.

Endpoints

Path	Purpose
POST /mcp	MCP Streamable HTTP endpoint
GET /healthz	Liveness, active sessions, exposed tool count, active policy

/healthz reports the policy in force, so the running security posture is auditable without reading the container environment.

Behaviour worth knowing

• Session renewal. DSM invalidates sessions on idle timeout, duplicate login and reboot. The client detects codes 106, 107 and 119, re-authenticates once and replays the call, so this never surfaces as a tool failure.
• API discovery. Endpoint paths and version ranges are read from SYNO.API.Info at runtime and cached, so the same build works across DSM 6 and DSM 7 and against APIs that moved between CGI handlers.
• Background tasks. Copy, move, delete, compress, extract, folder size and checksum all run asynchronously on the NAS. Each tool polls to completion instead of returning a task id, and reports partial progress if the timeout elapses.
• Error messages. DSM returns numeric codes inside a 200 OK body, and the same number means different things per API family. Codes are translated against the correct table and phrased as something you can act on.

Reference

Built against Synology's published File Station API, Download Station API and DSM Login Web API guides, plus runtime discovery via SYNO.API.Info.

License

MIT