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.

Related MCP server: mcp-synology

Tools

File Station — browse and read

File Station — write, archive and share

Download Station

Synology Photos

Container Manager

System

Generic bridge

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:

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

/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