Skip to content
Back to search

synology-mcp

MarketplaceWorks with Claude CodeGitHub

Use a Synology NAS (DSM 7) from Claude: MCP server, Claude Code plugin with a skill, and Claude Desktop extension

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/r03eRt/synology-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/r03eRt/synology-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/r03ert--synology-mcp/badge.svg)](/listings/r03ert--synology-mcp)

HTML

<a href="/listings/r03ert--synology-mcp"><img src="/api/listings/r03ert--synology-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

claude plugin marketplace add r03eRt/synology-mcp
claude plugin install synology@synology-mcp

Then, in Claude Code: `/plugin configure synology@synology-mcp`. Enter the NAS address (`http://192.168.1.10:5000` or `quickconnect:<your ID>`), the user and the password, and ask it whatever you want.

Using Claude Desktop? Download the `.mcpb` from [Releases](https://github.com/r03eRt/synology-mcp/releases) and open it. More options in [Install](#3-install).

> Independent project, not affiliated with Synology Inc. MIT License. Tested on a DS218+ with DSM 7.4.1.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "synology-mcp",
  3. "owner": { "name": "Roberto Morgado Luengo" },
  4. "metadata": {
  5. "description": "Synology NAS for Claude Code"
  6. },
  7. "plugins": [
  8. {
  9. "name": "synology",
  10. "source": "./plugin",
  11. "description": "Use a Synology NAS (DSM 7) from Claude: File Station, Synology Drive, Download Station and NAS status"
  12. }
  13. ]
  14. }
README.md · README · 543 lines
  1. **English** · [Español](README.es.md)
  2. <p align="center">
  3. <img src="docs/assets/banner.svg" alt="synology-mcp: your Synology NAS, in Claude's hands" width="100%">
  4. </p>
  5. <p align="center">
  6. <a href="https://github.com/r03eRt/synology-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/r03eRt/synology-mcp/actions/workflows/ci.yml/badge.svg"></a>
  7. <a href="https://github.com/r03eRt/synology-mcp/releases"><img alt="Release" src="https://img.shields.io/github/v/release/r03eRt/synology-mcp?color=d97757"></a>
  8. <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/github/license/r03eRt/synology-mcp"></a>
  9. <img alt="MCP" src="https://img.shields.io/badge/MCP-server-5f93d1">
  10. <img alt="DSM 7" src="https://img.shields.io/badge/Synology-DSM%207-0b1f3a">
  11. <img alt="Node 22.19+" src="https://img.shields.io/badge/node-%E2%89%A522.19-3c873a">
  12. </p>
  13. <p align="center">
  14. <b>Talk to your NAS.</b> Find files, manage downloads and containers, keep an eye on your disks and administer DSM<br>
  15. from <b>Claude Code</b> or <b>Claude Desktop</b>, at home or away with QuickConnect. Secure by default.
  16. </p>
  17. <p align="center">
  18. <a href="#quick-install">Quick install</a> ·
  19. <a href="#6-tools">111 tools</a> ·
  20. <a href="#5-security">Security</a> ·
  21. <a href="#7-example-requests">Examples</a> ·
  22. <a href="docs/en/README.md">Documentation</a>
  23. </p>
  24. ---
  25. ## What it looks like
  26. > **You:** How's the NAS doing?
  27. >
  28. > **Claude:** Everything is working, but there are three things worth a look:
  29. > - 🌡️ **41 °C**, up for 23 days. The volume is **89 %** full.
  30. > - 💽 Disk 1 has 8 reallocated sectors, **stable** over the last 12 checks; both disks have been running for almost 7 years.
  31. > - 🔒 There's a DSM **security update** and two packages with a new version.
  32. >
  33. > **You:** Free up some space.
  34. >
  35. > **Claude:** There's **6.7 GB** in recycle bins (almost all in Descargas) and Docker images no container uses, such as the previous Immich version (1.6 GB). Shall I empty the Descargas recycle bin and delete those images?
  36. Every answer comes from this server's tools running against your real NAS. Actions that delete or change something **always ask for confirmation**.
  37. ## What it can do
  38. | | Area | Most useful |
  39. |---|---|---|
  40. | 📁 | **Files** | Search by name, type, size or date · read documents and images · upload and download · move, compress · share with a link |
  41. | 🖼️ | **Synology Photos** | Albums · places · find photos by date, place or text, each with its path to open it · normal and self-filling albums · share albums by link |
  42. | ☁️ | **Synology Drive** | Recent, starred, labels, shared · share with people, links with password and expiry, file requests · convert to Synology Office |
  43. | ⬇️ | **Downloads** | Search torrents · URLs, magnets and `.torrent` · pick files · RSS · speed limits and schedule · detect dead downloads |
  44. | 🐳 | **Docker** | Container status, CPU/RAM and logs · start, stop and restart · create, edit and delete containers · pull and clean up images |
  45. | 🩺 | **Health** | SMART for each disk · pending updates · broken or stopped packages (and start or stop them) · notifications and logs · volumes |
  46. | 🧹 | **Space** | Recycle bins, unused images and the largest folders |
  47. | 🛠️ | **Administration** | Users and groups, shared folders and their permissions, scheduled tasks · warnings about insecure services (SMB1, FTP…) and turning them off · restart or shut down |
  48. | 🌍 | **Anywhere** | QuickConnect (local network, direct or Synology relay) · multiple NAS |
  49. ## Quick install
  50. ```bash
  51. claude plugin marketplace add r03eRt/synology-mcp
  52. claude plugin install synology@synology-mcp
  53. ```
  54. Then, in Claude Code: `/plugin configure synology@synology-mcp`. Enter the NAS address (`http://192.168.1.10:5000` or `quickconnect:<your ID>`), the user and the password, and ask it whatever you want.
  55. Using Claude Desktop? Download the `.mcpb` from [Releases](https://github.com/r03eRt/synology-mcp/releases) and open it. More options in [Install](#3-install).
  56. > Independent project, not affiliated with Synology Inc. MIT License. Tested on a DS218+ with DSM 7.4.1.
  57. ## Contents
  58. 1. [Requirements](#1-requirements)
  59. 2. [Set up a DSM user](#2-set-up-a-dsm-user)
  60. 3. [Install](#3-install)
  61. 4. [Configuration](#4-configuration)
  62. 5. [Security](#5-security)
  63. 6. [Tools](#6-tools)
  64. 7. [Example requests](#7-example-requests)
  65. 8. [Troubleshooting](#8-troubleshooting)
  66. 9. [Updating](#9-updating)
  67. 10. [Development](#10-development)
  68. 11. [Limitations and next steps](#11-limitations-and-next-steps)
  69. ## 1. Requirements
  70. - A Synology NAS with **DSM 7** (7.2 or later recommended), reachable from the computer where Claude runs:
  71. - by its IP or name, on the same network, over VPN or through an open port;
  72. - or via **QuickConnect** (`quickconnect:<your ID>`), which works from anywhere without opening ports.
  73. - **Node.js 22.19 or later** on that computer, for Claude Code or the manual install. Claude Desktop ships its own Node.
  74. - For each area, its package installed on the NAS: Synology Drive Server, Download Station or Container Manager. Tools for a package that isn't installed answer "is … installed?". `get_system_info` tells you which packages are present.
  75. ## 2. Set up a DSM user
  76. Claude can only do what the DSM user you configure is allowed to do; that is the main security barrier.
  77. **Recommended: a dedicated user without administrator rights.**
  78. 1. In *Control Panel → User & Group*, create a user, for example `claude`.
  79. 2. Under *Permissions*, give it read (or read/write) access **only** to the shared folders you want Claude to see.
  80. 3. Under *Applications*, allow File Station and, if you use them, Synology Drive and Download Station.
  81. What works with each kind of account:
  82. | With a regular user | Only with an administrator |
  83. |---|---|
  84. | Files, Drive, Download Station (its own downloads), `get_system_info` | Docker, NAS health (`get_system_utilization`, `get_storage_status`, `get_disk_health`, `check_updates`, `get_notifications`, `get_system_logs`), recycle bins, administration (`dsm_*`) and every user's downloads |
  85. Using an administrator gives Claude access to the whole NAS. If you do, consider keeping read-only mode on.
  86. **If your account has 2-step verification (2FA)**, register Claude once as a trusted device. It will ask for the authenticator code:
  87. ```bash
  88. SYNOLOGY_URL=http://192.168.1.10:5000 SYNOLOGY_USERNAME=claude SYNOLOGY_PASSWORD='…' npx synology-mcp register-device
  89. ```
  90. It prints `SYNOLOGY_DEVICE_ID=…`: put it in the configuration (field "2FA device token"). The device shows up in DSM (*Personal → Security*) and can be revoked there.
  91. ## 3. Install
  92. ### Claude Code: plugin (recommended)
  93. ```bash
  94. claude plugin marketplace add r03eRt/synology-mcp
  95. ```
  96. ```bash
  97. claude plugin install synology@synology-mcp
  98. ```
  99. Then, inside Claude Code, fill in the details with `/plugin configure synology@synology-mcp`. The password is stored in the system credential store. The plugin includes:
  100. - the server already bundled, with no dependencies to install;
  101. - the `synology-nas` skill, which teaches Claude to use the NAS well: paths, which tool to use for what, confirming before deleting or stopping services, and how to read disk health.
  102. ### Claude Desktop: extension
  103. Download `synology-mcp-<version>.mcpb` from [Releases](https://github.com/r03eRt/synology-mcp/releases) and double-click it. Claude Desktop asks for the same details and stores the password in the keychain.
  104. ### Manual install (any MCP client)
  105. > The npm package is **not published yet**: `npx synology-mcp` won't work until then. In the meantime, use the source.
  106. ```bash
  107. git clone https://github.com/r03eRt/synology-mcp.git
  108. ```
  109. ```bash
  110. cd synology-mcp && npm install && npm run build
  111. ```
  112. MCP client configuration:
  113. ```json
  114. {
  115. "mcpServers": {
  116. "synology": {
  117. "command": "node",
  118. "args": ["/path/to/synology-mcp/dist/index.js"],
  119. "env": {
  120. "SYNOLOGY_URL": "http://192.168.1.10:5000",
  121. "SYNOLOGY_USERNAME": "claude",
  122. "SYNOLOGY_PASSWORD": "…"
  123. }
  124. }
  125. }
  126. }
  127. ```
  128. To keep the password out of the client configuration, store it in a `.env` file with `600` permissions and start with `node --env-file=/path/to/.env /path/to/synology-mcp/dist/index.js`. In Claude Code:
  129. ```bash
  130. claude mcp add synology -s user -- node --env-file=/path/to/.env /path/to/synology-mcp/dist/index.js
  131. ```
  132. ## 4. Configuration
  133. | Variable | Plugin / extension field | Default | Purpose |
  134. |---|---|---|---|
  135. | `SYNOLOGY_URL` | NAS URL | — | DSM address with port (`http://IP:5000`, `https://nombre:5001`) or `quickconnect:<ID>` |
  136. | `SYNOLOGY_USERNAME` | DSM user | — | DSM user |
  137. | `SYNOLOGY_PASSWORD` | DSM password | — | Password |
  138. | `SYNOLOGY_READ_ONLY` | Read-only | `true` | `false` enables the 32 write tools (create, move, delete, download, stop containers, change permissions…) |
  139. | `SYNOLOGY_INSECURE_TLS` | Accept an invalid HTTPS certificate | `false` | Accepts a self-signed, expired or wrong-name HTTPS certificate. Only on a trusted network |
  140. | `SYNOLOGY_DEVICE_ID` | 2FA device token | — | Token from `register-device`, for accounts with 2FA |
  141. | `SYNOLOGY_DEVICE_NAME` | — | `synology-mcp` | Name the device was registered under |
  142. | `SYNOLOGY_TASK_TIMEOUT_MS` | — | `60000` | How long a tool waits for a long operation (copy, delete, search…) before returning its `taskid` to check later |
  143. | `SYNOLOGY_NAS_FILE` | — | — | JSON file with **multiple NAS** (see below). Replaces the first three variables |
  144. ### Using it away from home: QuickConnect
  145. Set `SYNOLOGY_URL=quickconnect:<ID>`, with the ID shown in DSM under *Control Panel → External Access → QuickConnect*, which must be enabled. When connecting, the MCP asks Synology's service where the NAS is and tries, in this order:
  146. 1. **Local network**: a `…direct.quickconnect.to` name pointing to the NAS's local IP.
  147. 2. **Direct connection over the Internet**, only if the NAS is reachable from outside.
  148. 3. **Synology's relay**: works from anywhere without opening ports, though it's slower.
  149. It uses the first one that answers. All three have a valid certificate, so `SYNOLOGY_INSECURE_TLS` isn't needed. If the connection drops (for example, when you leave home), it looks for the best route again on the next call. The ID is sent to Synology's service, just as Synology's own apps do.
  150. ### Multiple NAS
  151. With `SYNOLOGY_NAS_FILE=/path/to/nas.json` (permissions `600`):
  152. ```json
  153. {
  154. "default": "casa",
  155. "nas": [
  156. { "name": "casa", "url": "http://192.168.1.2:5000", "username": "claude", "password_env": "NAS_CASA_PASSWORD" },
  157. { "name": "padres", "url": "quickconnect:nas-padres", "username": "claude", "password_env": "NAS_PADRES_PASSWORD" }
  158. ]
  159. }
  160. ```
  161. - **Password**: `password_env` is the name of an environment variable that holds it, so it isn't stored in the file. `password` directly is also accepted.
  162. - **Other optional per-NAS fields**: `device_id` / `device_id_env` (2FA), `device_name` and `insecure_tls`.
  163. - **Global**: `SYNOLOGY_READ_ONLY` and `SYNOLOGY_TASK_TIMEOUT_MS` apply to all of them.
  164. - **Tools**: `list_nas` (which NAS exist, which is active and how each one is reached) and `use_nas` (switch NAS) appear; the rest act on the active one. Ask Claude "switch to my parents' NAS".
  165. - **2FA**: `register-device --nas <nombre>` registers the device on a specific one.
  166. - **In the plugin or the extension**: their form has a **second NAS** (name, URL, user, password, 2FA token), and a field for the path of this JSON file for three or more. Outside them, the same second NAS can be set with `SYNOLOGY_NAS2_URL`, `_USERNAME`, `_PASSWORD`, `_NAME`, `_DEVICE_ID` and `_INSECURE_TLS`, plus `SYNOLOGY_NAS_NAME` for the first one.
  167. Details, and how it's registered on the author's machine, in [docs/en/configuracion.md](docs/en/configuracion.md).
  168. ## 5. Security
  169. - **DSM permissions**: the MCP can never do more than the configured user.
  170. - **Read-only by default**: without `SYNOLOGY_READ_ONLY=false`, write tools don't exist for Claude.
  171. - **Confirmation before destroying.** These tools are marked as destructive, and the skill requires Claude to say what it's about to do and wait for your "yes":
  172. - deleting or overwriting files: `delete`, `copy_move`, `upload_file`, `write_text_file`, `extract`;
  173. - emptying recycle bins: `empty_recycle_bin`;
  174. - removing downloads or feeds: `downloads_delete`, `downloads_rss_delete`;
  175. - Docker: `docker_stop`, `docker_restart`, `docker_remove_images`, `docker_update_container`, `docker_delete_container`;
  176. - administration: `dsm_run_task` (runs a script), `dsm_set_share_access` (changes who sees what), `dsm_update_user`, `dsm_delete_user` (also deletes the home folder), `dsm_delete_group`, `dsm_delete_shared_folder` (deletes everything in it), `dsm_set_services` and `dsm_power` (restart or shut down);
  177. - Photos: `photos_delete_album`, `photos_share_album` (public link), `photos_edit_person` (merging can't be undone);
  178. - Drive: `drive_share`, `drive_link`, `drive_delete_file_request`, `drive_delete_label`;
  179. - others: `delete_sharing_links`.
  180. - **Secrets it never returns**, even if the NAS API provides them:
  181. - the **values** of container environment variables (database passwords, API keys); it only gives their names;
  182. - tracker **private keys (passkeys)** in torrent, RSS and magnet URLs, and credentials inside URLs; they come out as `<redacted>`;
  183. - passwords and keys inside **scheduled task scripts** (only a summary of the command is shown, with values hidden);
  184. - users' **emails**;
  185. - the **serial numbers** of the NAS and its disks.
  186. - **Credentials**: with the plugin or the extension, in the system's secure store. In the manual install, preferably in a `.env` with `600` permissions. The repository history contains no personal data.
  187. ## 6. Tools
  188. **Type**: *L* = read, *E* = write (only with `SYNOLOGY_READ_ONLY=false`), **D** = destructive (write that asks for confirmation). **Admin**: needs a DSM administrator account.
  189. **Paths**: file paths start with a shared folder (`/photo/2024/foto.jpg`, `/home/Documentos`); `/home` is the user's personal folder. Synology Drive uses `/mydrive/…` (the same folder as `/home/Drive`), `/team-folders/<nombre>/…` or `id:<file_id>`. Download destinations are NAS folders (`/home/Descargas`), and containers are named as in Container Manager.
  190. ### Files (File Station): 22
  191. | Tool | Type | What it does |
  192. |---|---|---|
  193. | `get_info` | L | NAS name, whether the user is admin, link support |
  194. | `list_shares` | L | Shared folders with free and total space |
  195. | `list_files` | L | Folder contents (sorting, filter, pagination) |
  196. | `get_file_info` | L | File or folder details |
  197. | `search_files` | L | Recursive search by name, extension, size, date or owner |
  198. | `get_dir_size` | L | Total size and file count of folders |
  199. | `get_md5` | L | MD5 of a file |
  200. | `read_file` | L | Contents of a text file or an image (up to 1 MB by default) |
  201. | `download_file` | L | Download to the computer (multiple files or a folder arrive as a ZIP) |
  202. | `list_sharing_links` | L | Public links created |
  203. | `list_background_tasks` / `get_task_status` | L | Long-running operations in progress and their progress |
  204. | `create_folder` | E | Create a folder (and its parents) |
  205. | `rename` | E | Rename |
  206. | `copy_move` | **D** | Copy or move (may overwrite) |
  207. | `delete` | **D** | Delete (recursive; treat it as permanent) |
  208. | `upload_file` | **D** | Upload a file from the computer (may overwrite) |
  209. | `write_text_file` | **D** | Create or replace a text file |
  210. | `compress` | E | Compress to ZIP or 7z (optional password) |
  211. | `extract` | **D** | Extract an archive (may overwrite) |
  212. | `create_sharing_link` | E | Public link, with optional password and expiry |
  213. | `delete_sharing_links` | **D** | Delete public links |
  214. ### NAS status and health: 9
  215. | Tool | Type | Admin | What it does |
  216. |---|---|---|---|
  217. | `get_system_info` | L | | Model, DSM, RAM, temperature, uptime, DSM's health verdict and which packages are installed |
  218. | `get_system_utilization` | L | yes | Live CPU, RAM, network and disk I/O |
  219. | `get_storage_status` | L | yes | Storage pools, RAID, volumes (usage, warnings) and disks |
  220. | `get_disk_health` | L | yes | SMART for each disk: bad sectors and whether they're growing, power-on hours, temperature, failing attributes |
  221. | `check_updates` | L | yes | DSM update (and whether it's a security one) and packages with a new version. Check only |
  222. | `get_notifications` | L | yes | DSM bell notifications (errors, warnings, finished downloads…) |
  223. | `get_packages` | L | yes | Installed packages and their status; flags the ones not working (e.g. incompatible with this DSM) and warns if Hyper Backup is missing |
  224. | `get_system_logs` | L | yes | System or connection log, filterable by level, text and dates |
  225. | `package_control` | **D** | yes | Start or stop a package. Won't stop system packages or start broken ones |
  226. ### Freeing up space: 2 (plus `docker_remove_images`)
  227. | Tool | Type | Admin | What it does |
  228. |---|---|---|---|
  229. | `recycle_bins` | L | yes | How much each shared folder's recycle bin takes up (largest first) and which have no recycle bin |
  230. | `empty_recycle_bin` | **D** | yes | Empty the given recycle bins. **Cannot be undone** |
  231. To find what else is taking up space, use `get_storage_status`, `get_dir_size`, `search_files` (with `size_from`) and `docker_images`.
  232. ### Synology Drive: 22
  233. | Tool | Type | What it does |
  234. |---|---|---|
  235. | `drive_list` / `drive_get_info` | L | List a folder / details of an item |
  236. | `drive_recent` / `drive_starred` | L | Recent / starred |
  237. | `drive_shared_with_me` / `drive_shared_with_others` | L | Shared with you / by you |
  238. | `drive_search` | L | Search by name, content, type, label, size or date |
  239. | `drive_list_labels` / `drive_list_labelled` | L | Labels / items with a label |
  240. | `drive_list_permissions` | L | Who has access to an item |
  241. | `drive_list_team_folders` | L | Team folders |
  242. | `drive_file_requests` | L | Your file requests (upload links) and their status |
  243. | `drive_star` | E | Star or unstar |
  244. | `drive_label` | E | Add or remove labels by name (creates missing ones) |
  245. | `drive_create_label` | E | Create a label |
  246. | `drive_delete_label` | **D** | Delete a label (files stay) |
  247. | `drive_convert_to_office` | E | Convert Word, Excel, PowerPoint or CSV to Synology Office |
  248. | `drive_create_file_request` | E | Create an upload link to a folder for people without a NAS account, with optional password and expiry |
  249. | `drive_update_file_request` | E | Change a file request (title, password, expiry), close it or reopen it |
  250. | `drive_share` | **D** | Give, change or remove a user's or group's role (viewer, editor, manager…) |
  251. | `drive_link` | **D** | Turn the sharing link on (NAS users or anyone) or off; with password or expiry, a protected link |
  252. | `drive_delete_file_request` | **D** | Delete file requests (uploaded files stay) |
  253. ### Synology Photos: 9
  254. `shared` space = the `/photo` folder (shared space); `personal` = your `/home/Photos`. Each photo comes with its NAS path, so Claude can open it with `read_file`.
  255. | Tool | Type | What it does |
  256. |---|---|---|
  257. | `photos_albums` | L | Your albums (or the ones shared with you): photos, dates, whether they're shared |
  258. | `photos_browse` | L | Places, people or tags, with how many photos each has |
  259. | `photos_list` | L | Photos in an album, of a person, at a place, with a tag, between two dates or matching a text search; with `details`, place, camera and resolution |
  260. | `photos_create_album` | E | Create an album, optionally with photos |
  261. | `photos_album_items` | E | Add photos to an album or take them out (they stay in the library) |
  262. | `photos_delete_album` | **D** | Delete albums (the photos stay) |
  263. | `photos_create_condition_album` | E | Self-filling album by place (by name), dates and/or text, e.g. "Madrid 2025"; says how many photos match |
  264. | `photos_share_album` | **D** | Public link to an album (view or download), with password and expiry, or turn it off |
  265. | `photos_edit_person` | **D** | Name, hide or merge people found by face recognition |
  266. ### Downloads (Download Station): 17
  267. A regular user sees and manages their own downloads; an administrator, everyone's.
  268. | Tool | Type | What it does |
  269. |---|---|---|
  270. | `downloads_info` | L | Version, default folder, limits, current speed, queue and speed schedule |
  271. | `downloads_search` | L | Search torrents with Download Station's search engines; results sorted by seeds, ready for `downloads_add` |
  272. | `downloads_list` | L | Downloads with status, progress and speed. Filters by status, type, text or **dead downloads** (`stalled`: active but with no speed or peers for over an hour, usually torrents removed from the tracker) |
  273. | `downloads_get` | L | Details: source, files, peers and trackers |
  274. | `downloads_files` | L | Files in a torrent with their index, progress, priority and whether they're being downloaded |
  275. | `downloads_rss` | L | Subscribed RSS feeds, or the items of one (filterable by text) |
  276. | `downloads_add` | E | Add URLs, magnets or `.torrent` files from the computer, with optional destination folder and extraction password |
  277. | `downloads_pause` / `downloads_resume` | E | Pause or resume |
  278. | `downloads_set_destination` | E | Change the destination folder |
  279. | `downloads_set_files` | E | Choose which files of a torrent to download and their priority |
  280. | `downloads_rss_add` / `downloads_rss_refresh` | E | Subscribe to a feed / refresh feeds |
  281. | `downloads_set_limits` | E | Speed limits per protocol (KB/s) and how many downloads run at once |
  282. | `downloads_set_schedule` | E | Weekly schedule: hours at full speed, limited or paused (e.g. only at night) |
  283. | `downloads_delete` | **D** | Remove downloads. What's already complete is kept; with `move_incomplete`, incomplete data too |
  284. | `downloads_rss_delete` | **D** | Remove RSS subscriptions |
  285. To clean up dead downloads: ask "which downloads are dead?" (`downloads_list` with `stalled`) and then "remove them" (`downloads_delete`, with confirmation).
  286. ### Docker (Container Manager): 12
  287. All require an administrator account: DSM doesn't let other users use Container Manager.
  288. | Tool | Type | What it does |
  289. |---|---|---|
  290. | `docker_list` | L | Containers with status, health, image, uptime, Compose project, CPU and memory |
  291. | `docker_get` | L | Ports, volumes (NAS folder → container), networks, restart policy, last *health check* and **only the names** of environment variables |
  292. | `docker_logs` | L | A container's log, with text and date filters. May take 20–60 s |
  293. | `docker_images` | L | Images with size, whether any container uses them and whether there's an update |
  294. | `docker_start` | E | Start containers |
  295. | `docker_stop` / `docker_restart` | **D** | Stop or restart. Their service goes down (DNS, password manager…) |
  296. | `docker_remove_images` | **D** | Delete images no container uses (images in use are rejected) |
  297. | `docker_pull_image` | E | Download an image from Docker Hub |
  298. | `docker_create_container` | E | Create a container: ports, folders, variables, restart policy, network |
  299. | `docker_update_container` | **D** | Change a stopped container (variables, ports, folders, name…) |
  300. | `docker_delete_container` | **D** | Delete stopped containers (mounted folders keep their data) |
  301. ### DSM administration: 18
  302. All require an administrator account.
  303. | Tool | Type | What it does |
  304. |---|---|---|
  305. | `dsm_users` | L | Users with status (active, disabled, expired), whether they're administrators and their groups. No emails |
  306. | `dsm_groups` | L | Groups and their members |
  307. | `dsm_shared_folders` | L | Shared folders (path, space, hidden, encrypted, recycle bin, USB) or, for one folder, who has access and what kind |
  308. | `dsm_user_access` | L | Which folders a user can access, combining their permissions and their groups' (deny wins) |
  309. | `dsm_scheduled_tasks` | L | Scheduled tasks: enabled or not, next run, last result and a secret-free summary of the command |
  310. | `dsm_services` | L | SMB, AFP, NFS, FTP, SSH, Telnet and DSM web, with **warnings** about insecure settings: SMB1, unencrypted FTP, Telnet, DSM without HTTPS redirect… |
  311. | `dsm_set_task_enabled` | E | Enable or disable scheduled tasks |
  312. | `dsm_run_task` | **D** | Run a task now (runs its script, often as root) |
  313. | `dsm_set_share_access` | **D** | Grant or remove folder access for a user or group: read/write, read-only, deny or none |
  314. | `dsm_create_user` | E | Create a user with groups; without a password it generates one and shows it once |
  315. | `dsm_update_user` | **D** | Change description, groups or password, or disable/enable the account. Won't lock out the MCP's own account |
  316. | `dsm_delete_user` | **D** | Delete users and their home folder. Won't delete itself, `admin` or `guest` |
  317. | `dsm_create_group` / `dsm_delete_group` | E / **D** | Create a group with members / delete groups (not the built-in ones) |
  318. | `dsm_create_shared_folder` | E | Create a shared folder (then grant access with `dsm_set_share_access`) |
  319. | `dsm_delete_shared_folder` | **D** | Delete shared folders **and their contents**. Refuses non-empty ones unless told explicitly |
  320. | `dsm_set_services` | **D** | SMB minimum version (drop SMB1), FTP, Telnet, SSH and its port, HTTPS redirect |
  321. | `dsm_power` | **D** | Restart or shut down the NAS (asks to repeat the word; lists running tasks first) |
  322. ### Multiple NAS: 2 (only if more than one is configured)
  323. | Tool | Type | What it does |
  324. |---|---|---|
  325. | `list_nas` | L | Configured NAS, which is active and how each one is reached (address; with QuickConnect, whether local network, direct or relay) |
  326. | `use_nas` | L | Switch the active NAS; the other tools then act on it. Changes nothing on any NAS |
  327. Full reference (parameters, the DSM API each one uses and responses) in [docs/en/herramientas.md](docs/en/herramientas.md).
  328. ## 7. Example requests
  329. **Status**
  330. - "How's the NAS doing? Any disk with problems?"
  331. - "Are there pending updates? What errors have there been this week?"
  332. - "Who has logged into the NAS today?"
  333. - "Is any package broken or stopped? Do I have backups?"
  334. **Space**
  335. - "The volume is almost full: what can I delete?"
  336. - "How much space do the recycle bins take? Empty the Descargas one."
  337. - "Delete the Docker images that aren't in use."
  338. **Files**
  339. - "Find the 2024 invoice PDFs in /home and tell me how much space they take."
  340. - "Read /home/notas/lista.txt and summarize it."
  341. - "Create a share link for /photo/Viaje that expires on Sunday."
  342. - "Share the Proyecto Drive folder with marta as an editor."
  343. - "Create a link so my family can upload the wedding photos to Drive."
  344. **Downloads**
  345. - "Add this magnet in /home/Descargas."
  346. - "From the series torrent, download only episodes 1 to 3."
  347. - "Which downloads are dead? Remove them."
  348. - "Subscribe to this RSS feed and tell me what's new."
  349. - "Search for the Ubuntu 24.04 ISO torrent and add the one with the most seeds."
  350. - "Only download at night on weekdays, and cap uploads at 200 KB/s."
  351. **Administration**
  352. - "Who can see the photo folder?"
  353. - "Is any insecure service enabled?"
  354. - "Which scheduled tasks failed last time?"
  355. - "Remove marta's access to Documents."
  356. - "Create a user for Lucía with read-only access to photo."
  357. **Photos**
  358. - "Show me the photos from Scotland in July 2025."
  359. - "Make an album with the best ones from Madrid."
  360. - "Open the latest photo Marta uploaded."
  361. **Docker**
  362. - "Which containers are stopped? Show me pihole's latest errors."
  363. - "Restart jellyfin."
  364. **Drive**
  365. - "List what I've starred in Drive."
  366. - "Label the PDFs in /mydrive/2024 as "Taxes"."
  367. ## 8. Troubleshooting
  368. | Message | What's happening | What to do |
  369. |---|---|---|
  370. | `Missing required environment variables` | The URL, user or password is missing | Check the configuration (section 4) |
  371. | `Cannot reach the NAS at …` | No connection to that address | Check the IP, the port (5000 http, 5001 https) and that you're on the NAS's network. Away from home, use `quickconnect:<ID>` |
  372. | `QuickConnect ID "…" was not found` | The ID doesn't exist | Copy it from *Control Panel → External Access → QuickConnect* |
  373. | `none of its … addresses answered` | QuickConnect is disabled or the NAS is off | Enable it in DSM and check the NAS has a connection |
  374. | `TLS error … (CERT_HAS_EXPIRED)` or similar | HTTPS certificate expired, self-signed or for another name | Renew it in *Control Panel → Security → Certificate*, use the certificate's name or set `SYNOLOGY_INSECURE_TLS=true` |
  375. | `No such account or incorrect password (code 400)` | Wrong credentials | Repeating it many times blocks the IP (code 407) |
  376. | `2-step verification code required (code 403)` | The account has 2FA | Run `register-device` (section 2) |
  377. | `needs a DSM administrator account (code 105)` | The tool is admin-only | Use an account in the *administrators* group or do without it |
  378. | `… not be allowed to use <package> (code 105)` | The user doesn't have permission for that application | Grant it in *Control Panel → Application Privileges* |
  379. | `is <package> installed …? (code 102)` | That package isn't installed | Install it from Package Center |
  380. | Write tools are missing | It's in read-only mode | `SYNOLOGY_READ_ONLY=false` |
  381. | `finished: false` with a `taskid` | The operation is still running | Ask Claude to check it later (`get_task_status`) |
  382. ## 9. Updating
  383. - Plugin: `claude plugin marketplace update synology-mcp`, then `claude plugin update synology@synology-mcp`, and restart Claude Code.
  384. - Claude Desktop: install the `.mcpb` from the latest [release](https://github.com/r03eRt/synology-mcp/releases).
  385. - Manual: `git pull && npm install && npm run build`, and restart the client.
  386. Each version's changes are in the [CHANGELOG](CHANGELOG.en.md).
  387. ## 10. Development
  388. ```bash
  389. npm install
  390. npm run typecheck # types for src/ and test/
  391. npm run build # dist/ (npm package)
  392. npm run bundle # plugin/server/synology-mcp.cjs: the server in a single file, for the plugin and the extension
  393. npm run pack:mcpb # build/synology-mcp-<version>.mcpb
  394. npm test # regenerates the bundle and runs the tests against a simulated NAS, no network
  395. SYNOLOGY_ENV_FILE=.env.admin npm run test:real # optional: against a real NAS, in a temporary folder in /home
  396. ```
  397. ```
  398. src/
  399. index.ts startup (stdio) and register-device command
  400. server.ts server creation and tool registration
  401. config.ts environment variables
  402. synology/client.ts login (Noise v7 / v6 / 2FA), requests, uploads, connection errors
  403. synology/errors.ts error code messages
  404. synology/noise.ts Noise handshake for the DSM 7.2 login
  405. synology/quickconnect.ts QuickConnect ID resolution (local network, direct or relay)
  406. synology/pool.ts multiple NAS: the active client and switching between them
  407. tools/filestation.ts files
  408. tools/system.ts get_system_info, utilization and storage
  409. tools/health.ts SMART, updates, notifications and logs
  410. tools/space.ts recycle bins
  411. tools/drive.ts Synology Drive
  412. tools/photos.ts Synology Photos
  413. tools/downloadstation.ts Download Station (tasks, torrent files, RSS, search, limits, schedule)
  414. tools/docker.ts Container Manager
  415. tools/nas.ts list_nas and use_nas (with multiple NAS)
  416. tools/admin.ts DSM administration (dsm_*)
  417. test/ unit tests, simulated NAS (test/mock) and real NAS (test/real)
  418. plugin/ Claude Code plugin: manifest, skill and bundled server
  419. .claude-plugin/ marketplace
  420. mcpb/manifest.json Claude Desktop extension
  421. docs/ technical documentation (Spanish; English in docs/en/)
  422. ```
  423. Technical documentation in [docs/](docs/en/README.md):
  424. - [tools](docs/en/herramientas.md): full reference;
  425. - [Synology API](docs/en/api-synology.md): undocumented behaviors discovered while testing;
  426. - [authentication](docs/en/autenticacion.md);
  427. - [architecture](docs/en/arquitectura.md);
  428. - [testing](docs/en/pruebas.md);
  429. - [distribution](docs/en/distribucion.md);
  430. - [roadmap](docs/en/hoja-de-ruta.md).
  431. To add something: find the call in the DSM web UI (the NAS serves its JavaScript), try it by hand, write the tool with its test in `test/mock/`, document it and bump the version in `package.json`, `src/server.ts`, `plugin/.claude-plugin/plugin.json` and `mcpb/manifest.json` (a test checks that they match).
  432. ## 11. Limitations and next steps
  433. - **npm**: the package isn't published yet.
  434. - **Not tested in practice**: 2FA (tested only with the simulated NAS) and the installed Claude Desktop extension.
  435. - **Not included**: Hyper Backup (not installed on the test NAS, so its API couldn't be taken), uploading through Photos, editing groups, quotas, encryption, firewall and network settings, Compose projects. See the [roadmap](docs/en/hoja-de-ruta.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.