Synology NAS

mcp-synology

MCP server for Synology NAS devices. Exposes Synology DSM API functionality as MCP tools that Claude can use.

Tested against DSM 7.1.1-42962 Update 9, 7.2.2-72806 Update 10, 7.3.2-86009 Update 5 and 7.4.1-90080 Update 1: CI runs the integration tests for every module on a virtual DSM of each. Release candidates are also live-tested on a real NAS (DSM 7.1.1-42962 Update 9) by AI clients driving the tools: for 0.10.0, Claude Code, claude.ai through the desktop app, and Meta Muse, as admin, regular, read-only and restricted users. See docs/live-testing.md.

Supported modules

Each module covers one DSM package. A module loads only when it's listed under modules: in the config, and its permission decides whether you get its READ tools only or its WRITE tools too.

Coverage, per tier, of what the package itself can do: ✅ Full: everything; 🟢 Most: the main features, with gaps listed under the module; 🟡 Partial: the core features, with notable gaps; — no tools in that tier.

What's not covered yet, in short:

• System: process list, system health, logs, connected users. No WRITE tools (no reboot or shutdown).
• File Station: compress and extract, share links, favorites, thumbnails, MD5 checksums, permissions and ownership changes, mounting remote folders.
• Synology Photos: timeline and similar-photo views, video streaming, Shared Space folder permissions, face-level People edits, guest uploads to photo requests, Photos' own settings.
• Download Station: BT search, RSS feeds, choosing files inside a torrent, editing a torrent's trackers, settings other than speed limits and the default destination.
• Storage: no WRITE tools yet (phase 2: scrubbing, S.M.A.R.T. tests, hot spares, settings, snapshots); no iSCSI LUNs and SAN Manager, Hyper Backup or Task Scheduler. Never anything that wipes disks or changes a pool's layout.

Tested clients

Each release candidate is live-tested by these clients driving the tools on a real NAS (how):

A client can change the outcome on its own: the same model does less well through a client that drops the server's instructions or annotations.

Tested models

For best results, use Claude Sonnet 5.5 or better. The live tests above ran on Claude Opus 5.5 in both Claude clients. To compare models, we held the client fixed: headless Claude Code (server instructions and full tool schemas delivered, no other tools), the same 12 tasks across System, File Station, Synology Photos and Download Station (Storage came later), on a DSM 7.2.2 test NAS restored fresh for each model, as a non-admin user (2026-10-28).

Both handled Photos uploads, albums and tags, recycle-bin checks, Download Station tasks and honest answers about what isn't supported. The task Haiku missed needed an extra lookup it didn't think to make (matching a download by its source URL); Sonnet made it. Haiku is fine for reads; for writes, and deletes above all, use Sonnet or better. The tasks, how each was graded and the per-task results are in Comparing models.

Quick Start

1. Run setup

uvx mcp-synology setup

Requires uv. uvx downloads the latest version and caches it — no separate install step needed. It checks PyPI again once its cached copy of the index is more than 10 minutes old, so a restart of your MCP client usually picks up a new release; see Updates.

Setup will prompt for your NAS host, credentials, and preferences. If your account has 2FA enabled, it will prompt for an OTP code and store a device token for automatic future logins. It writes a config with the File Station module only; add other modules afterward (see each module below).

At the end, it prints a Claude Desktop JSON snippet ready to copy-paste.

2. Add to Claude Desktop

Copy the snippet from setup into your claude_desktop_config.json and restart Claude Desktop. It will look something like:

{

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

The config file name (e.g., nas.yaml) also serves as a natural identifier for the connection — you can name it to match your NAS (e.g., home-nas.yaml, office-nas.yaml).

On Linux, the server auto-detects the D-Bus session socket for keyring access. If auto-detection fails, add "env": {"DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/ /bus"} to the Claude Desktop config. The setup command includes this in the generated snippet.

3. Verify

uvx mcp-synology check --config <your config file>   # Validates the config and credentials (setup prints this line; ~/.config/mcp-synology/config.yaml needs no flag)

uvx mcp-synology setup --list # Shows all configured NAS instances

Adding a module

1. Install the package on the NAS (Synology Photos or Download Station) from Package Center, if it isn't installed already. Without it the module's tools still appear, but every call fails with api_not_found.
2. Edit your config file: the one setup wrote (the file your client's --config names), or the per-NAS file such as home-nas.yaml if you use Multi-NAS. Add the module inside the existing `modules:` section; don't add a second modules: key. Each module below has a block to copy.
3. Check the config: mcp-synology check --config runs the same validation as serve, so it lists the YAML, setting and module-setting mistakes it finds and names the file. It also names misspelled settings and modules, and confirms the login still works.
4. Restart your MCP client (for example, Claude Desktop). The server reads its config only at startup.

Alternative: global install

If you prefer a persistent install (avoids download on each invocation). Requires uv — install with curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or see the installation guide for other options.

uv tool install mcp-synology

mcp-synology setup mcp-synology check --config

Alternative: env-var-only mode

No config file needed if SYNOLOGY_HOST is set, as long as no ./mcp-synology.yaml is in the working folder: one there stops the server until it's named or moved, or you start from another folder, so give an MCP client a fixed working folder if it has that setting. This is useful for Docker or CI environments:

{

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