synology-mcp

MCP server for managing a Synology NAS (DSM 7) from Claude or any other MCP client: system health, disks, files, Container Manager, accounts, security, Photos, Drive, Synology Office and any other DSM API your NAS offers.

Status: early (0.2.1). A test on a real NAS with a non-administrator account confirmed the file tools, Drive search, and reading, exporting, importing and copying Synology Office files. Tools that need an administrator (system, storage, accounts), Photos and editing .osheet cells have not been confirmed on a real NAS yet. See Verification status.

• Only the tools that apply. At startup the server reads the NAS's own API list (SYNO.API.Info, no login needed) and hides whatever isn't installed, so a package you don't have costs no context.

• 2FA without repeated codes. setup exchanges one code for a trusted-device token, stored in the Keychain.

• The NAS's certificate is pinned. DSM's default certificate is self-signed. Instead of turning verification off, its fingerprint is pinned and checked on every connection, before the password is sent.

• It won't get your IP blocked. Refused credentials are never sent again, so they can't trip DSM's Auto Block.

• Risky changes ask first. Deleting, sharing publicly or stopping a package returns a preview before anything happens.

• Any DSM API. dsm_api_search and dsm_read reach every API on the NAS, including those with no dedicated tool.

Install and connect

Requires Node 22 or newer.

npm install -g github:joaomelorodrigues/synology-mcp
synology-mcp setup --url https://nas.example.com:5001

To update, run the first command again. Settings and secrets live outside the package, so they are kept.

setup shows the NAS's certificate and asks to pin it, then asks for the username, the password (hidden), the permission tier and the 2FA code. It finishes by printing the command that connects your client, for example:

claude mcp add --scope user synology -- /path/to/node /path/to/dist/index.js serve

To check the connection and try the read tools against your NAS:

synology-mcp doctor

The report contains no secrets.

The port is part of the address. DSM uses 5001 (HTTPS) and 5000 (HTTP) by default, and ports 443 and 80 may be serving Web Station instead. If the address you give isn't DSM, setup tries the usual ports. You can find yours in Control Panel > Login Portal.

If the NAS is only reachable over a VPN, tools return an error saying so while the VPN is down, and work again once it's back.

The claude mcp add command that setup prints points at your current Node version. If you use nvm and switch versions, install again and rerun that command.

Related MCP server: mcp-server-synology

Permission tiers

The tier is set with tier. Tools above it are never registered, so the model has no way to call them by mistake.

At any tier, secrets (OTP, encryption keys, account recovery) and changes to the disk layout (creating, deleting or repairing pools and volumes) stay out of reach. Those are left to DSM itself.

Configuration

Settings live in ~/.config/synology-mcp/config.json, which holds no secrets. Environment variables take priority; see .env.example.

{
  "url": "https://nas.example.com:5001",
  "username": "mcp-admin",
  "tier": "write",
  "allowPower": false,
  "modules": "all",
  "certFingerprint": "AB:CD:EF:...",
  "localRoots": ["~/Downloads"],
  "protectedPaths": ["/backups"],
  "instructions": "Backups are in /backups. Always confirm before touching /docker."
}

The server reads its settings at startup, so restart your MCP client after changing them.

Tools

synology-mcp tools --hidden lists this connection's tools and their context cost. On a NAS with Container Manager, Photos, Drive and Synology Office, but without Hyper Backup, Download Station, VMM or Surveillance Station, that is 68 tools at read (about 11k tokens), 99 at write (17k) and 111 at admin (19k). If you don't need an area, leave its module out of modules.

Tools for a package that isn't installed stay hidden. They appear once you install it and restart your client.

Synology Office

Office files are addressed by Drive path (/mydrive/Budget.osheet), by link_id (which drive_list and drive_search return) or by their /oo/r/ URL. There are two ways in.

Through DSM, with nothing else to install. The office_* tools read any spreadsheet, document or presentation as text or in full, create empty files, convert CSV and Microsoft or OpenDocument files into Office files, export to xlsx, docx, pptx, ods, odt and odp, and manage versions, attachments, templates, themes and settings.

Synology doesn't document these SYNO.Office.* APIs. Their methods and parameters come from the web client that Synology Office 3.7.2 serves. office_apis lists them all with the tool that reaches each, and office_call calls any method without a dedicated tool. Of the 49 APIs on the NAS these were read from, Synology's client never calls 10, so their methods are unknown: Doc.Snapshot, Group, Metrics, Notification, OFile, Permission, Permission.User, Presentation.Snapshot, Resource and Shard.JSConfig. The client also names 3 APIs that NAS doesn't offer: Doc.Outline, Cluster.Status and Sheet.Snapshot.Worksheet. Only what a NAS lists can be called, so office_sheet_copy appears only where it's available.

These APIs have limits:

• They can't edit the cells of an existing .osheet. Synology's client doesn't do that through them either.

• PDF and CSV exports aren't available, because Synology's client builds those in the browser. The sheet_export tool can give CSV.

• Saving or publishing a template needs a thumbnail upload, which has no tool.

Through the official Spreadsheet API, to edit cells in place. The sheet_* tools read and write ranges, append rows, format cells, and manage tabs, rows and columns in the live file. They need Synology's synology/spreadsheet-api container, which isn't part of the Office package:

1. Deploy docker-compose.spreadsheet.yml, with Portainer or docker compose. The image tag must match your Synology Office: 3.4.x for Office 3.7.0 or later, 3.3.x for Office 3.6.x. Synology advises against running it on the same DSM as Office when many spreadsheets are active, since each open spreadsheet gets its own worker.

2. Make it reachable securely. The container takes DSM passwords over plain HTTP, so its port is published on loopback only, and this server refuses to send a password to it over plain HTTP from another machine. Either add an HTTPS reverse proxy (Control Panel > Login Portal > Advanced > Reverse Proxy, destination http://localhost:3000), or open an SSH tunnel: ssh -N -L 3000:127.0.0.1:3000 you@your-nas.

3. Run synology-mcp spreadsheet-setup --url https://your-proxy:port, or --url http://127.0.0.1:3000 through the tunnel. It pins an HTTPS certificate and tests a login through the container before storing anything.

4. Restart your MCP client.

Two more things to expect from this container:

• 2FA. Its login accepts no 2FA code, as far as a third-party project reports, so a 2FA account needs a dedicated DSM account without 2FA.

• Certificates. It can't verify DSM's self-signed certificate, so point it at DSM's http port. That traffic stays private only if the container runs on the NAS itself.

How 2FA works

1. setup logs in with your password and a code, and asks DSM for a trusted-device token.

2. The password and token are stored in the macOS Keychain (on other systems, in a file with mode 600).

3. Later logins use the token, with no code.

If you remove the trusted device in DSM (Personal > Security > Sign-in Activity), the next error says what to do: either give the model a current code, which it passes to nas_auth_otp, or run setup again.

Security

• The password and token always travel in a POST body, never in a URL, and are never written to replies or logs.

• Container environment variables and Compose files can hold secrets, so they are returned only when explicitly requested. dsm_read hides fields with names like password or token.

• Content from the NAS (files, names, logs) can contain text written by anyone. The server's instructions tell the model to treat it as data.

• files_delete, files_rename and moves through files_copy_move refuse a whole shared folder, because in DSM that removes the shared folder itself, beyond its recycle bin. share_delete does that on purpose, and requires typing the name back.

• read is the default tier. If you use a dedicated DSM account with fewer privileges, DSM's own limits apply on top of these.

If you replace the NAS's certificate, connections are refused until you run synology-mcp trust-cert. This is deliberate: someone intercepting the connection would cause the same error.

Running on another machine over HTTP

By default the client starts the server locally over stdio, so you don't need to host it. To keep it always on, for example on the NAS itself:

docker compose run --rm -it synology-mcp setup --url https://nas.example.com:5001
SYNOLOGY_MCP_TOKEN=$(openssl rand -hex 32) docker compose up -d

The endpoint is http://127.0.0.1:8765/mcp. Beyond loopback, the server refuses to start without SYNOLOGY_MCP_TOKEN and SYNOLOGY_MCP_ALLOWED_HOSTS. To expose it, put an HTTPS reverse proxy in front. Anyone who reaches this endpoint with the token can do whatever the configured tier allows.

Troubleshooting

Development

git clone https://github.com/joaomelorodrigues/synology-mcp.git
cd synology-mcp
npm install
npm test                         # compiles, then tests against a fake DSM over real HTTP
TEST_KEYCHAIN=1 npm test         # also tests the real Keychain, with a temporary item
npm run typecheck

dist/ is committed because it is what npm install -g installs. With -g, a package from git that has a script named build, prepare, prepack, preinstall, install or postinstall ends up as a symlink to a temporary folder npm has already deleted, which is why the compile script is called compile. After changing src/, run npm run compile and include dist/ in the commit. The GitHub Actions check fails if you forget.

The code is split into src/dsm (DSM client: session, TLS, errors), src/mcp (tool registry, output formats, path guards, HTTP transport), src/tools (tools by area) and src/cli (setup, doctor, tools). To add a tool, add a tool({...}) in src/tools with its tier and the APIs it depends on.

Verification status

The tests cover the server's behavior against a simulated DSM. On a real NAS, with a non-administrator account, these have been confirmed: login, listing, searching, reading, downloading, writing, uploading, copying, renaming and deleting files, creating folders, searching Drive, and reading, exporting, importing and copying Synology Office files. The shape of the other calls comes from the reference projects below, which tested them on DSM 7.x, but it still needs confirming:

• Renaming with office_update and office_version_action were corrected after that test and have not run on a real NAS since. Their calls come from Synology Office 3.7.2's web client. doctor tries the Office read tools on the first .osheet it finds.

• No sheet_* tool has run against the real container. Synology's API reference is not public, so their calls follow vocweb/synology-mcp-server, which is itself tested mostly against mocks.

• Read tools can be confirmed with doctor, using an administrator account for system, storage and accounts. Some have no equivalent in the references, so watch those first: security_login_activity, drive_labels, and photos_items with no source given.

• The 2FA flow can be confirmed by running setup on an account that uses it.

• Write tools can only be confirmed by using them. Try them on unimportant data first, especially files_compress, which also has no equivalent in the references.

References

The DSM API conventions were learned from these projects: cmeans/mcp-synology, rafalr100/synology-mcp, atom2ueki/mcp-server-synology and vocweb/synology-mcp-server. The code here is original.

License

MIT. Not affiliated with Synology Inc.