Skip to content
Back to search

mcp-server-synology

πŸ’Ύ Model Context Protocol (MCP) server for Synology NAS - Enables AI assistants (Claude, Cursor, Continue) to manage files, downloads, and system operations through secure API integration. Features Docker deployment, auto-authentication, and comprehensive file system tools.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

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

HTML

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

Install

i

Install instructions from the README

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

No need to clone the repository β€” install the package directly from PyPI:

# With pip
pip install mcp-server-synology

# Or with pipx (isolated environment)
pipx install mcp-server-synology

# Or with uv
uv tool install mcp-server-synology

This installs two equivalent commands: `synology-mcp` and `mcp-server-synology`.

For MCP clients, `uvx` is the simplest option β€” it downloads and caches the package automatically, no manual install or local clone required:

{
  "mcpServers": {
    "synology": {
      "command": "uvx",
      "args": ["mcp-server-synology"]
    }
  }
}

Configuration lives outside the package, so it works the same as a source checkout: create `~/.config/synology-mcp/settings.json` as described in [Configuration Options](#️-configuration-options).

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.

README.md Β· README Β· 888 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # πŸ’Ύ Synology MCP Server
  2. ![Synology MCP Server](assets/banner.png)
  3. A Model Context Protocol (MCP) server for Synology NAS devices. Enables AI assistants to manage files and downloads through secure authentication and session management.
  4. **🌟 NEW: Unified server supports both Claude/Cursor (stdio) and Xiaozhi (WebSocket) simultaneously!**
  5. ## πŸ“¦ Install from PyPI
  6. No need to clone the repository β€” install the package directly from PyPI:
  7. ```bash
  8. # With pip
  9. pip install mcp-server-synology
  10. # Or with pipx (isolated environment)
  11. pipx install mcp-server-synology
  12. # Or with uv
  13. uv tool install mcp-server-synology
  14. ```
  15. This installs two equivalent commands: `synology-mcp` and `mcp-server-synology`.
  16. For MCP clients, `uvx` is the simplest option β€” it downloads and caches the package automatically, no manual install or local clone required:
  17. ```json
  18. {
  19. "mcpServers": {
  20. "synology": {
  21. "command": "uvx",
  22. "args": ["mcp-server-synology"]
  23. }
  24. }
  25. }
  26. ```
  27. Configuration lives outside the package, so it works the same as a source checkout: create `~/.config/synology-mcp/settings.json` as described in [Configuration Options](#️-configuration-options).
  28. ## πŸš€ Quick Start with Docker
  29. ### 1️⃣ Setup Environment
  30. ```bash
  31. # Clone repository
  32. git clone https://github.com/atom2ueki/mcp-server-synology.git
  33. cd mcp-server-synology
  34. # Create environment file
  35. cp env.example .env
  36. ```
  37. ### 2️⃣ Configure .env File
  38. **Basic Configuration (Claude/Cursor only):**
  39. ```bash
  40. # Required: Synology NAS connection
  41. SYNOLOGY_URL=http://192.168.1.100:5000
  42. SYNOLOGY_USERNAME=your_username
  43. SYNOLOGY_PASSWORD=your_password
  44. # Optional: Auto-login on startup
  45. AUTO_LOGIN=true
  46. VERIFY_SSL=false
  47. ```
  48. **Extended Configuration (Both Claude/Cursor + Xiaozhi):**
  49. ```bash
  50. # Required: Synology NAS connection
  51. SYNOLOGY_URL=http://192.168.1.100:5000
  52. SYNOLOGY_USERNAME=your_username
  53. SYNOLOGY_PASSWORD=your_password
  54. # Optional: Auto-login on startup
  55. AUTO_LOGIN=true
  56. VERIFY_SSL=false
  57. # Enable Xiaozhi support
  58. ENABLE_XIAOZHI=true
  59. XIAOZHI_TOKEN=your_xiaozhi_token_here
  60. XIAOZHI_MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/
  61. ```
  62. `.env` is read at **run time**, never baked into the image β€” `docker-compose.yml`
  63. injects its entries as container environment variables via `env_file`, so the
  64. file itself is not present inside the container. It is optional: if you
  65. configure NASes with `settings.json` instead (recommended), you can skip this
  66. file entirely.
  67. ### 3️⃣ Run with Docker
  68. **One simple command supports both modes:**
  69. ```bash
  70. # Claude/Cursor only mode (default if ENABLE_XIAOZHI not set)
  71. docker-compose up -d
  72. # Both Claude/Cursor + Xiaozhi mode (if ENABLE_XIAOZHI=true in .env)
  73. docker-compose up -d
  74. # Build and run
  75. docker-compose up -d --build
  76. ```
  77. ### 4️⃣ Alternative: Local Python
  78. ```bash
  79. # Install the package and its dependencies (from PyPI, or from a clone with 'pip install .')
  80. pip install mcp-server-synology
  81. # Run with environment control
  82. python main.py
  83. ```
  84. ## πŸ”Œ Client Setup
  85. The examples below use Docker with a local clone of this repository. If you installed from PyPI, use the `uvx` configuration from [Install from PyPI](#-install-from-pypi) instead β€” it works for Claude Desktop, Cursor, Continue and Codeium alike, with no local paths to adjust.
  86. ### πŸ€– Claude Desktop
  87. Add to your Claude Desktop configuration file:
  88. **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
  89. **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
  90. ```json
  91. {
  92. "mcpServers": {
  93. "synology": {
  94. "command": "docker-compose",
  95. "args": [
  96. "-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
  97. "run", "--rm", "synology-mcp"
  98. ],
  99. "cwd": "/path/to/your/mcp-server-synology"
  100. }
  101. }
  102. }
  103. ```
  104. ### ↗️ Cursor
  105. Add to your Cursor MCP settings:
  106. ```json
  107. {
  108. "mcpServers": {
  109. "synology": {
  110. "command": "docker-compose",
  111. "args": [
  112. "-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
  113. "run", "--rm", "synology-mcp"
  114. ],
  115. "cwd": "/path/to/your/mcp-server-synology"
  116. }
  117. }
  118. }
  119. ```
  120. ### πŸ”„ Continue (VS Code Extension)
  121. Add to your Continue configuration (`.continue/config.json`):
  122. ```json
  123. {
  124. "mcpServers": {
  125. "synology": {
  126. "command": "docker-compose",
  127. "args": [
  128. "-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
  129. "run", "--rm", "synology-mcp"
  130. ],
  131. "cwd": "/path/to/your/mcp-server-synology"
  132. }
  133. }
  134. }
  135. ```
  136. ### πŸ’» Codeium
  137. For Codeium's MCP support:
  138. ```json
  139. {
  140. "mcpServers": {
  141. "synology": {
  142. "command": "docker-compose",
  143. "args": [
  144. "-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
  145. "run", "--rm", "synology-mcp"
  146. ],
  147. "cwd": "/path/to/your/mcp-server-synology"
  148. }
  149. }
  150. }
  151. ```
  152. ### 🐍 Alternative: Direct Python Execution
  153. If you prefer not to use Docker:
  154. ```json
  155. {
  156. "mcpServers": {
  157. "synology": {
  158. "command": "python",
  159. "args": ["main.py"],
  160. "cwd": "/path/to/your/mcp-server-synology",
  161. "env": {
  162. "SYNOLOGY_URL": "http://192.168.1.100:5000",
  163. "SYNOLOGY_USERNAME": "your_username",
  164. "SYNOLOGY_PASSWORD": "your_password",
  165. "AUTO_LOGIN": "true",
  166. "ENABLE_XIAOZHI": "false"
  167. }
  168. }
  169. }
  170. }
  171. ```
  172. ## 🌐 Remote Streamable HTTP Deployment
  173. By default the server speaks **stdio**, which means the MCP client has to spawn the process locally (or via a bridge such as SSH/docker exec). For setups where the NAS is remote (different machine from where Claude/Cursor runs), set `MCP_HTTP=true` and the server serves **native Streamable HTTP** from uvicorn in the same process β€” no `mcp-proxy` sidecar and no separate `/sse` endpoint. This makes it consumable by any MCP client that supports URL-based connectors β€” exactly like `ha-mcp` or other "remote" MCP servers.
  174. ### Architecture
  175. ```
  176. [Claude Desktop / Cursor / ...]
  177. β”‚
  178. β”‚ HTTPS (URL connector)
  179. β–Ό
  180. [Reverse proxy: DSM / Nginx / Traefik / Caddy]
  181. β”‚ (TLS termination + auth)
  182. β”‚ HTTP localhost:8765
  183. β–Ό
  184. [Docker container]
  185. └─ python main.py
  186. └─ uvicorn β†’ Streamable HTTP at /mcp
  187. ```
  188. ### Deploy
  189. 1. All dependencies come from `pyproject.toml`: `mcp>=2.0.0` ships starlette,
  190. uvicorn, and sse-starlette, so the same image serves both stdio and
  191. Streamable HTTP β€” no extra build arg or separate requirements file.
  192. 2. Use the provided `docker-compose.http.yml`:
  193. ```bash
  194. # Edit credentials in docker-compose.http.yml first
  195. docker compose -f docker-compose.http.yml up -d --build
  196. docker logs -f synology-mcp-http
  197. ```
  198. You should see the server log `Starting Streamable HTTP MCP server on http://0.0.0.0:8765/mcp` and the auto-login succeed. uvicorn's own `Uvicorn running on …` banner is *not* printed at the compose file's defaults β€” it is INFO on the `uvicorn.error` logger, which the server pins to `warning` unless `DEBUG=true`.
  199. ### Reverse proxy
  200. Most MCP clients require HTTPS, so the HTTP endpoint must be fronted by a TLS-terminating reverse proxy. For DSM users, the built-in **Login Portal β†’ Reverse Proxy** does the job:
  201. - **Source**: `HTTPS`, hostname `synology-mcp.example.com`, port `443`
  202. - **Destination**: `HTTP`, `localhost`, port `8765`
  203. - **Custom Headers**: none required β€” Streamable HTTP is plain POST/GET on a single endpoint, not a WebSocket upgrade. The *Create β†’ WebSocket* preset is harmless if you already apply it elsewhere (it sets `Connection: upgrade` only for real upgrade requests), but it is not what keeps a stream open
  204. For Nginx, the equivalent is:
  205. ```nginx
  206. location / {
  207. proxy_pass http://localhost:8765;
  208. proxy_http_version 1.1;
  209. proxy_set_header Host $host;
  210. proxy_set_header X-Real-IP $remote_addr;
  211. proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  212. proxy_set_header X-Forwarded-Proto $scheme;
  213. # Responses may stream as long-lived text/event-stream
  214. proxy_buffering off;
  215. proxy_cache off;
  216. proxy_read_timeout 24h;
  217. }
  218. ```
  219. ### Client configuration
  220. In Claude Desktop (or any MCP client that supports remote connectors), add a custom connector pointing at:
  221. ```
  222. https://synology-mcp.example.com/mcp
  223. ```
  224. The path is whatever `MCP_HTTP_PATH` is set to (default `/mcp`). No `command`, no `args`, no local Python β€” just a URL.
  225. ### Security
  226. The server does **not** implement any application-level authentication β€” anything that can reach the HTTP endpoint can call every tool. It does enable the MCP SDK's DNS-rebinding protection, which rejects requests whose `Host`/`Origin` headers are not on an allowlist (`MCP_HTTP_ALLOWED_HOSTS` / `MCP_HTTP_ALLOWED_ORIGINS`, defaulting to loopback). Behind a reverse proxy set both, minding the differing formats β€” hosts are bare (`synology-mcp.example.com`), origins are scheme-qualified (`https://synology-mcp.example.com`), as in the commented examples in `docker-compose.http.yml`. That guards browsers against rebinding attacks; it is **not** authentication. Mitigations:
  227. - Keep it on a private network or behind a VPN
  228. - Leave the published port on loopback (`docker-compose.http.yml` binds `127.0.0.1:8765`) so only a same-host reverse proxy can reach it
  229. - Use the reverse proxy to enforce an IP allow-list
  230. - Add Basic Auth / mTLS / OAuth2 proxy at the reverse proxy layer
  231. - Use a dedicated low-privilege DSM user (already recommended in the security warning above)
  232. ## 🌟 Xiaozhi Integration
  233. **New unified architecture supports both clients simultaneously!**
  234. ### How It Works
  235. - **ENABLE_XIAOZHI=false** (default): Standard MCP server for Claude/Cursor via stdio
  236. - **ENABLE_XIAOZHI=true**: Multi-client bridge supporting both:
  237. - πŸ“‘ **Xiaozhi**: WebSocket connection
  238. - πŸ’» **Claude/Cursor**: stdio connection
  239. ### Setup Steps
  240. 1. **Add to your .env file:**
  241. ```bash
  242. ENABLE_XIAOZHI=true
  243. XIAOZHI_TOKEN=your_xiaozhi_token_here
  244. ```
  245. 2. **Run normally:**
  246. ```bash
  247. # Same command, different behavior based on environment
  248. python main.py
  249. # OR
  250. docker-compose up
  251. ```
  252. ### Key Features
  253. - βœ… **Zero Configuration Conflicts**: One server, multiple clients
  254. - βœ… **Parallel Operation**: Both clients can work simultaneously
  255. - βœ… **All Tools Available**: Xiaozhi gets access to all Synology MCP tools
  256. - βœ… **Backward Compatible**: Existing setups work unchanged
  257. - βœ… **Auto-Reconnection**: Handles WebSocket connection drops
  258. - βœ… **Environment Controlled**: Simple boolean flag to enable/disable
  259. ### Startup Messages
  260. **Claude/Cursor only mode:**
  261. ```
  262. πŸš€ Synology MCP Server
  263. ==============================
  264. πŸ“Œ Claude/Cursor only mode (ENABLE_XIAOZHI=false)
  265. ```
  266. **Both clients mode:**
  267. ```
  268. πŸš€ Synology MCP Server with Xiaozhi Bridge
  269. ==================================================
  270. 🌟 Supports BOTH Xiaozhi and Claude/Cursor simultaneously!
  271. ```
  272. ## πŸ› οΈ Available MCP Tools
  273. ### πŸ” Authentication
  274. - **`synology_status`** - Check authentication status and active sessions
  275. - **`synology_list_nas`** - List all configured NAS units from settings.json
  276. - **`synology_login`** - Authenticate with Synology NAS *(conditional)*
  277. - **`synology_logout`** - Logout from session *(conditional)*
  278. ### πŸ“ File System Operations
  279. - **`list_shares`** - List all available NAS shares
  280. - **`list_directory`** - List directory contents with metadata
  281. - `path` (required): Directory path starting with `/`
  282. - **`get_file_info`** - Get detailed file/directory information
  283. - `path` (required): File path starting with `/`
  284. - **`get_file_content`** - Read strict UTF-8 text or lossless base64 content
  285. - `path` (required): File path starting with `/`
  286. - `encoding` (optional): `text` (default) or `base64`
  287. - `max_bytes` (optional): Maximum raw bytes to read (default 1 MiB, hard limit 8 MiB)
  288. - **`search_files`** - Recursively search for files and folders by name
  289. - `path` (required): Search directory
  290. - `pattern` (required): Case-insensitive substring of the name (e.g., `invoice`, `.pdf`). Wildcards are not special β€” DSM matches `report` and `*report*` identically.
  291. - **`create_file`** - Create new files with content
  292. - `path` (required): Full file path starting with `/`
  293. - `content` (optional): File content (default: empty string)
  294. - `overwrite` (optional): Overwrite existing files (default: false)
  295. - `encoding` (optional): `text` (default) or strict `base64`; decoded content is limited to 8 MiB
  296. - **`create_directory`** - Create new directories
  297. - `folder_path` (required): Parent directory path starting with `/`
  298. - `name` (required): New directory name
  299. - `force_parent` (optional): Create parent directories if needed (default: false)
  300. - **`delete`** - Delete files or directories (auto-detects type)
  301. - `path` (required): File/directory path starting with `/`
  302. - **`rename_file`** - Rename files or directories
  303. - `path` (required): Current file path
  304. - `new_name` (required): New filename
  305. - **`move_file`** - Move files to new location
  306. - `source_path` (required): Source file path
  307. - `destination_path` (required): Destination path
  308. - `overwrite` (optional): Overwrite existing files
  309. - **`copy_file`** - Copy a regular file inside the NAS without sending its bytes through the MCP client
  310. - `source_path` (required): Source file path
  311. - `destination_folder` (required): Existing destination directory; the filename is preserved
  312. - `overwrite` (optional): Overwrite an existing same-named file (default: false)
  313. `copy_file` verifies the destination path and byte count. It is not a consistent
  314. backup method for a live SQLite database; use SQLite's online backup mechanism
  315. for databases that may be changing during the copy.
  316. ### πŸ“₯ Download Station Management
  317. - **`ds_get_info`** - Get Download Station information
  318. - **`ds_list_tasks`** - List all download tasks with status
  319. - `offset` (optional): Pagination offset
  320. - `limit` (optional): Max tasks to return
  321. - **`ds_create_task`** - Create new download task
  322. - `uri` (required): Download URL or magnet link
  323. - `destination` (optional): Download folder path
  324. - **`ds_pause_tasks`** - Pause download tasks
  325. - `task_ids` (required): Array of task IDs
  326. - **`ds_resume_tasks`** - Resume paused tasks
  327. - `task_ids` (required): Array of task IDs
  328. - **`ds_delete_tasks`** - Delete download tasks
  329. - `task_ids` (required): Array of task IDs
  330. - `force_complete` (optional): Force delete completed
  331. - **`ds_get_statistics`** - Get download/upload statistics
  332. ### πŸ₯ Health Monitoring
  333. - **`synology_system_info`** - Get system model, serial, DSM version, uptime, temperature
  334. - **`synology_utilization`** - Get real-time CPU, memory, swap, and disk I/O utilization
  335. - **`synology_disk_health`** - List all physical disks with SMART status, model, temp, size
  336. - **`synology_disk_smart`** - Get detailed SMART attributes for a specific disk
  337. - **`synology_volume_status`** - List all volumes with status, size, usage, filesystem type
  338. - **`synology_storage_pool`** - List RAID/storage pools with level, status, member disks
  339. - **`synology_lun_list`** - List all iSCSI LUNs with name, UUID, size, type, status and backing volume. To see which target a LUN is attached to, use `synology_target_list` - DSM does not report mappings on the LUN side.
  340. - **`synology_lun_get`** - Get details for a single iSCSI LUN
  341. - `name` (required): LUN name or UUID from `synology_lun_list` output
  342. - **`synology_network`** - Get network interface status and transfer rates
  343. ### SAN Manager (iSCSI provisioning)
  344. Wraps `SYNO.Core.ISCSI.LUN` and `SYNO.Core.ISCSI.Target`. Verified against DSM
  345. 7.3.2-86009 Update 4 on an RS1221+; other DSM builds may differ, and DSM's own
  346. refusal is reported as given rather than second-guessed.
  347. - **`synology_lun_create`** - Create a LUN on a volume; returns its `uuid` and `lun_id`
  348. - `name`, `location` (e.g. `/volume2`), `size` (**in bytes**) required
  349. - `type` (optional): `thin` (default, DSM `BLUN`), `advanced`, `file`, or a raw
  350. DSM type name. Note `thin` and `THIN` are **different**: lowercase is the
  351. friendly alias for `BLUN`, uppercase is DSM's distinct legacy type. Thick
  352. types were refused on the btrfs volume this was tested against.
  353. - `description` (optional)
  354. - **`synology_lun_delete`** - **DESTRUCTIVE.** Delete a LUN and everything on it
  355. - `uuid` and `confirm: true` required
  356. - **`synology_target_list`** - List targets with IQN, auth type, and the LUNs mapped to each
  357. - **`synology_target_get`** - Get one target by `target_id`
  358. - **`synology_target_create`** - Create a target; returns its `target_id`
  359. - `name` required; `iqn` defaults to `iqn.2000-01.com.synology:<name>`
  360. - `chap_user` + `chap_password` enable CHAP. **Supply both or neither** -
  361. one alone, or an empty string, is refused rather than quietly producing a
  362. target with no authentication. **With neither, the target accepts any
  363. initiator that can reach it.**
  364. - `max_sessions` (optional, 0 = DSM default)
  365. - **`synology_target_map_lun`** - Map LUNs to a target (`target_id`, `lun_uuids`)
  366. - **`synology_target_unmap_lun`** - **DESTRUCTIVE.** Unmap LUNs, disconnecting any
  367. initiator using them (`target_id`, `lun_uuids`, `confirm: true`)
  368. These tools reject any argument they do not declare, rather than ignoring it: a
  369. misspelled `chap_user` would otherwise create an unauthenticated target, and a
  370. misspelled `type` would silently take the default.
  371. - **`synology_ups`** - Get UPS status, battery level, power readings
  372. - **`synology_services`** - List installed packages and their running status
  373. - **`synology_system_log`** - Get recent system log entries
  374. - **`synology_health_summary`** - Aggregate system info, utilization, disk health, and volume status
  375. ### 🐳 Container Manager
  376. - **`synology_container_list`** - List Container Manager containers
  377. - `offset` (optional): Pagination offset
  378. - `limit` (optional): Maximum containers to return
  379. - `container_type` (optional): Container filter (default: `all`)
  380. - **`synology_container_health_summary`** - Summarize container status, health, restart counts, and images
  381. - **`synology_container_disk_usage`** - Show the read-only disk-usage summary available through Container Manager APIs
  382. - **`synology_container_get`** - Get a Container Manager container
  383. - `name` (required): Container name
  384. - **`synology_container_start`** - Start a Container Manager container
  385. - `name` (required): Container name
  386. - **`synology_container_stop`** - Stop a Container Manager container
  387. - `name` (required): Container name
  388. - **`synology_container_restart`** - Restart a Container Manager container
  389. - `name` (required): Container name
  390. - **`synology_container_delete`** - Delete a Container Manager container
  391. - `name` (required): Container name
  392. - `force` (optional): Force deletion (default: false)
  393. - `preserve_profile` (optional): Preserve Synology container profile (default: true)
  394. - **`synology_container_logs`** - Get Container Manager container logs
  395. - `name` (required): Container name
  396. - `since` (optional): Log start time/filter
  397. - `offset` (optional): Pagination offset (default: 0)
  398. - `limit` (optional): Maximum log lines to return (default: 1000)
  399. - **`synology_container_resource`** - Get real-time resource usage for a Container Manager container
  400. - `name` (required): Container name
  401. - **`synology_container_project_list`** - List Container Manager projects
  402. - **`synology_container_project_get`** - Get a Container Manager project (Compose, environment, and secret fields are omitted)
  403. - `name` (required): Project name
  404. - **`synology_container_project_create`** - Create and save a Container Manager project definition
  405. - `name` (required): Project name
  406. - `share_path` (required): Project folder path on the NAS
  407. - `content` (required): Docker Compose YAML content
  408. - `enable_service_portal` (optional): Enable Synology service portal (default: false)
  409. - `service_portal_name` (optional): Service portal name
  410. - `service_portal_port` (optional): Service portal port
  411. - `service_portal_protocol` (optional): Service portal protocol (default: `http`)
  412. - Saves the Compose definition; call `synology_container_project_build` to materialize it.
  413. - **`synology_container_project_update`** - Update a Container Manager project
  414. - `name` (required): Project name
  415. - `content` (required): Docker Compose YAML content
  416. - `enable_service_portal` (optional): Enable Synology service portal
  417. - `service_portal_name` (optional): Service portal name
  418. - `service_portal_port` (optional): Service portal port
  419. - `service_portal_protocol` (optional): Service portal protocol
  420. - **`synology_container_project_start`** - Start a Container Manager project
  421. - `name` (required): Project name
  422. - **`synology_container_project_stop`** - Stop a Container Manager project
  423. - `name` (required): Project name
  424. - **`synology_container_project_restart`** - Restart a Container Manager project
  425. - `name` (required): Project name
  426. - **`synology_container_project_build`** - Materialize or rebuild a saved Container Manager project
  427. - `name` (required): Project name
  428. - **`synology_container_project_clean`** - Clean a Container Manager project
  429. - `name` (required): Project name
  430. - **`synology_container_project_delete`** - Delete a Container Manager project
  431. - `name` (required): Project name
  432. - **`synology_container_image_list`** - List Container Manager images
  433. - `offset` (optional): Pagination offset
  434. - `limit` (optional): Maximum images to return
  435. - `show_dsm` (optional): Include DSM images (default: false)
  436. - **`synology_container_image_get`** - Get a Container Manager image
  437. - `name` (required): Image repository name
  438. - `tag` (optional): Image tag (default: `latest`)
  439. - **`synology_container_image_delete`** - Delete a Container Manager image
  440. - `name` (required): Image repository name
  441. - `tag` (optional): Image tag (default: `latest`)
  442. - **`synology_container_image_prune`** - Remove images unused by any container
  443. - **`synology_container_image_prune_preview`** provides a read-only candidate list before cleanup
  444. - Uses only Container Manager APIs to delete safely identifiable unused tagged images and reports dangling images it cannot remove through DSM
  445. - Does not remove containers, networks, or build cache
  446. - **`synology_container_image_pull`** - Pull a Container Manager image
  447. - `repository` (required): Image repository name
  448. - `tag` (optional): Image tag (default: `latest`)
  449. - **`synology_container_registry_list`** - List Container Manager registries
  450. - **`synology_container_registry_search`** - Search Container Manager registries
  451. - `query` (required): Image search query
  452. - `offset` (optional): Pagination offset
  453. - `limit` (optional): Maximum results to return
  454. - **`synology_container_registry_tags`** - List tags for a registry image
  455. - `repository` (required): Image repository name
  456. - `offset` (optional): Pagination offset
  457. - `limit` (optional): Maximum tags to return
  458. - **`synology_container_registry_download`** - Download a registry image
  459. - `repository` (required): Image repository name
  460. - `tag` (optional): Image tag (default: `latest`)
  461. - **`synology_container_network_list`** - List Container Manager networks
  462. - **`synology_container_network_get`** - Get a Container Manager network
  463. - `name` (required): Network name
  464. - **`synology_container_network_create`** - Create a Container Manager network
  465. - `name` (required): Network name
  466. - `driver` (optional): Network driver (default: `bridge`)
  467. - `subnet` (optional): Subnet CIDR
  468. - `gateway` (optional): Gateway IP
  469. - `ip_range` (optional): Allocatable IP range CIDR
  470. - `enable_ipv6` (optional): Enable IPv6 (default: false)
  471. - **`synology_container_network_delete`** - Delete a Container Manager network
  472. - `name` (required): Network name
  473. ### πŸ“¦ NFS Management
  474. - **`synology_nfs_status`** - Get NFS service status and configuration
  475. - **`synology_nfs_enable`** - Enable or disable the NFS service
  476. - **`synology_nfs_list_shares`** - List all shared folders with their NFS permissions
  477. - **`synology_nfs_set_permission`** - Set NFS client access permissions on a shared folder
  478. ### πŸ”€ Login Portal Reverse Proxy
  479. - **`synology_reverse_proxy_list`** - List reverse proxy entries (Control Panel β†’ Login Portal β†’ Advanced β†’ Reverse Proxy) with source, destination, HSTS, WebSocket, custom headers and access control profile
  480. - **`synology_reverse_proxy_get`** - Get one entry by UUID or description
  481. - **`synology_access_control_profile_list`** - List the access control profiles an entry can reference
  482. - **`synology_reverse_proxy_create`** - Create an entry; refused if the description is already in use
  483. - **`synology_reverse_proxy_update`** - Change some fields of an entry, keeping the rest
  484. - **`synology_reverse_proxy_delete`** - **DESTRUCTIVE.** Delete an entry *(requires `confirm=true`)*
  485. - Every write makes DSM rebuild and reload its nginx configuration, which can take a minute on small NAS models. A write that times out is reported with `outcome_unknown: true` β€” list before retrying.
  486. ## 🧠 Claude Code / Claude.ai Skill
  487. For Claude Code, Claude Desktop, and claude.ai users, this repo ships an Anthropic Agent Skill that teaches Claude how to use the MCP tools effectively β€” picking the right tool, targeting the right NAS in multi-NAS setups, preferring aggregate health checks over fan-out calls, and using correct path conventions.
  488. The skill lives at [`skills/synology-nas/`](skills/synology-nas/) and uses progressive disclosure across seven domains (auth, files, downloads, health, containers, shares/NFS, user management).
  489. **Install:**
  490. - **Claude Code**: copy or symlink the folder into `~/.claude/skills/synology-nas/`
  491. - **Claude.ai / Claude Desktop**: upload the `synology-nas/` folder via the Skills settings page
  492. The skill is purely additive β€” it works alongside the MCP and only triggers on Synology/NAS-related prompts.
  493. ## βš™οΈ Configuration Options
  494. > **⚠️ Security Warning: Use a Dedicated Account**
  495. >
  496. > For this MCP server, create a dedicated Synology user account with appropriate permissions. This account should:
  497. > - Have minimal required permissions only (not admin!)
  498. > - Be used exclusively for MCP server automation
  499. > - **2FA is now supported** β€” if your DSM account has 2FA enabled, see the
  500. > [2FA / OTP Accounts](#2fa--otp-accounts-optional) section below to supply
  501. > an `otp_code` (one-shot) or `device_id` (persistent) field. Older guidance
  502. > of "no 2FA" is no longer required.
  503. ### Using settings.json (Recommended)
  504. | Variable | Required | Default | Description |
  505. |----------|----------|---------|-------------|
  506. | `SYNOLOGY_URL` | Yes* | - | NAS base URL (e.g., `http://192.168.1.100:5000`) |
  507. | `SYNOLOGY_USERNAME` | Yes* | - | Username for authentication |
  508. | `SYNOLOGY_PASSWORD` | Yes* | - | Password for authentication |
  509. | `AUTO_LOGIN` | No | `true` | Auto-login on server start |
  510. | `VERIFY_SSL` | No | `false` | Verify SSL certificates |
  511. | `DEBUG` | No | `false` | Enable debug logging |
  512. | `ENABLE_XIAOZHI` | No | `false` | Enable Xiaozhi WebSocket bridge |
  513. | `XIAOZHI_TOKEN` | Xiaozhi only | - | Authentication token for Xiaozhi |
  514. | `XIAOZHI_MCP_ENDPOINT` | No | `wss://api.xiaozhi.me/mcp/` | Xiaozhi WebSocket endpoint |
  515. *Required for auto-login and default operations
  516. ### Using settings.json (Multi-NAS Support)
  517. For managing multiple Synology NAS devices, use the XDG standard config directory (`~/.config/synology-mcp/settings.json`):
  518. ```bash
  519. mkdir -p ~/.config/synology-mcp
  520. touch ~/.config/synology-mcp/settings.json
  521. chmod 600 ~/.config/synology-mcp/settings.json # Important: secure permissions!
  522. ```
  523. **Note:** This follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) - `~/.config/` is the standard location for user configuration files on Linux/macOS. You can customize the location by setting the `XDG_CONFIG_HOME` environment variable.
  524. **With Docker:**
  525. The docker-compose.yml automatically mounts your `~/.config/synology-mcp` directory into the container at `/home/mcpuser/.config/synology-mcp`, so multi-NAS works out of the box with Docker as well.
  526. **settings.json format:**
  527. ```json
  528. {
  529. "synology": {
  530. "nas1": {
  531. "host": "192.168.1.100",
  532. "port": 5000,
  533. "username": "admin",
  534. "password": "your_password",
  535. "note": "Primary NAS at home"
  536. },
  537. "nas2": {
  538. "host": "192.168.1.200",
  539. "port": 5001,
  540. "username": "admin",
  541. "password": "your_password",
  542. "note": "Backup NAS"
  543. },
  544. "nas3": {
  545. "url": "https://nas.example.com",
  546. "username": "admin",
  547. "password": "your_password",
  548. "note": "NAS behind a reverse proxy"
  549. }
  550. },
  551. "xiaozhi": {
  552. "enabled": false,
  553. "token": "your_xiaozhi_token",
  554. "endpoint": "wss://api.xiaozhi.me/mcp/"
  555. },
  556. "server": {
  557. "auto_login": true,
  558. "verify_ssl": false,
  559. "session_timeout": 3600,
  560. "debug": false,
  561. "log_level": "INFO"
  562. }
  563. }
  564. ```
  565. **Configuration fields:**
  566. | Field | Required | Description |
  567. |-------|----------|-------------|
  568. | `host` | Yes* | NAS hostname or IP address |
  569. | `port` | No | API port (default: 5000 for HTTP, 5001 for HTTPS) |
  570. | `url` | Yes* | Full base URL (e.g., `https://nas.example.com`); wins over `host`/`port` β€” use for a NAS behind a reverse proxy |
  571. | `username` | Yes | NAS username |
  572. | `password` | Yes | NAS password |
  573. | `otp_code` | No | One-shot 6-digit 2FA code (first login only, then remove) |
  574. | `device_id` | No | Long-lived trusted-device token from DSM (`did`); skip OTP on all future logins |
  575. | `note` | No | Optional description for your reference |
  576. *Either `host` or `url` is required per NAS entry.
  577. **Notes:**
  578. - The server will use port 5001 (HTTPS) if port is 5001, otherwise defaults to HTTP (5000)
  579. - The `host`/`port` form always appends a port and derives the scheme from it, so it cannot express `https://nas.example.com` on the default 443 β€” set `url` directly for reverse-proxied setups
  580. - File permissions: `chmod 600 ~/.config/synology-mcp/settings.json` is required for security
  581. - The server will refuse to load settings if permissions are too open
  582. - Both .env and settings.json can be used together (settings.json takes priority)
  583. ### ⚠️ Security Recommendations
  584. **settings.json File Permissions:**
  585. - **Linux/macOS (POSIX):** `chmod 600 ~/.config/synology-mcp/settings.json` is required. The server refuses to load the file if it is group- or world-readable/writable, or owned by another user.
  586. - **Windows:** Access control is enforced via NTFS ACLs, not POSIX mode bits. The server audits the file's security descriptor and refuses to load unless **all three** hold: (1) the owner SID matches the current user; (2) the DACL is present (a NULL DACL β€” "everyone full access" β€” is rejected); (3) no allow-ACE grants access to a principal outside the allowlist: the current user, `NT AUTHORITY\SYSTEM`, and `BUILTIN\Administrators`. Any inherited `Everyone` / `BUILTIN\Users` / `Authenticated Users` grant fails the check.
  587. - Requires the optional [`pywin32`](https://pypi.org/project/pywin32/) package: `pip install pywin32`. **If pywin32 is not installed, the server fails closed and refuses to load `settings.json`.** Operators who accept the risk of an unverified file can opt back in by setting `SYNOLOGY_MCP_ALLOW_UNVERIFIED_WINDOWS_ACL=true`.
  588. - The server resolves the file via `XDG_CONFIG_HOME` (default `Path.home() / ".config"`), so on Windows it lives at `%USERPROFILE%\.config\synology-mcp\settings.json` unless `XDG_CONFIG_HOME` is set.
  589. - Lock down the file from an elevated PowerShell prompt (uses the same path the server loads):
  590. ```powershell
  591. # Resolve the path the SAME way the server does: $XDG_CONFIG_HOME if set,
  592. # otherwise %USERPROFILE%\.config. This honors the override documented above.
  593. $cfg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$env:USERPROFILE\.config" }
  594. $f = "$cfg\synology-mcp\settings.json"
  595. # The server's ACL audit requires: owner == current user, no NULL DACL, and
  596. # no allow-ACE outside {current user, SYSTEM, Administrators}. The steps
  597. # below enforce all three.
  598. #
  599. # Use the *<SID> form for every built-in principal: account names like
  600. # "Administrators" / "Everyone" / "Users" are localized on non-English
  601. # Windows (e.g. German "Administratoren") and won't resolve. The
  602. # locale-independent SIDs:
  603. # *S-1-1-0 Everyone
  604. # *S-1-5-11 Authenticated Users
  605. # *S-1-5-32-545 BUILTIN\Users
  606. # *S-1-5-32-544 BUILTIN\Administrators
  607. #
  608. # 1. Ensure the file is owned by the current user (the audit rejects any
  609. # other owner). /setowner requires elevation.
  610. icacls $f /setowner "${env:USERNAME}"
  611. # 2. Drop inherited ACEs, then revoke the common foreign grants. /grant:r
  612. # only replaces the named principal, so revoke first.
  613. icacls $f /inheritance:r
  614. icacls $f /remove:g "*S-1-1-0" "*S-1-5-11" "*S-1-5-32-545"
  615. # Re-run `icacls $f` here; if any principal other than your user or
  616. # Administrators still appears, run: icacls $f /remove:g "<that principal>"
  617. # 3. Grant the current user and Administrators full control.
  618. icacls $f /grant:r "${env:USERNAME}:(F)"
  619. icacls $f /grant:r "*S-1-5-32-544:(F)" # BUILTIN\Administrators (locale-independent)
  620. ```
  621. If the file is brand new, the `/remove:g` step is a harmless no-op.
  622. - Verify: `icacls "$f"` β€” only your user and `*S-1-5-32-544` (Administrators) should appear.
  623. **SSL Certificate Verification (VERIFY_SSL):**
  624. - Default is `false` to support self-signed certificates on internal NAS devices
  625. - **If your NAS has a valid SSL certificate (e.g., from Let's Encrypt or a corporate CA), set `VERIFY_SSL=true`**
  626. - Setting `VERIFY_SSL=false` disables certificate verification and makes your connection vulnerable to man-in-the-middle (MITM) attacks
  627. - Never disable SSL verification on untrusted networks
  628. **Auto-Login (AUTO_LOGIN):**
  629. - Default is `true` for convenience with settings.json
  630. - Credentials are stored securely in `~/.config/synology-mcp/settings.json` with 0600 permissions
  631. - If you prefer manual login, set `AUTO_LOGIN=false` and use the `synology_login` tool
  632. **2FA / OTP Accounts (optional):**
  633. The MCP server supports DSM accounts with 2FA enabled. There are two ways to use it:
  634. 1. **One-shot OTP via `synology_login` tool** (interactive):
  635. ```json
  636. { "base_url": "https://nas.lan:5001", "username": "alice", "password": "…", "otp_code": "123456" }
  637. ```
  638. DSM will return a `did` (device token) in the response β€” copy that value into `settings.json` (below) to skip OTP on future process restarts.
  639. 2. **Persistent trusted-device token** (recommended for `AUTO_LOGIN=true`):
  640. Add `otp_code` (one-shot, **first login only**) and/or `device_id` (long-lived, ongoing) fields per-NAS in `settings.json`:
  641. ```json
  642. {
  643. "synology": {
  644. "nas1": {
  645. "host": "192.168.1.100", "port": 5001,
  646. "username": "alice", "password": "…",
  647. "otp_code": "123456",
  648. "note": "primary β€” 2FA enabled"
  649. }
  650. }
  651. }
  652. ```
  653. **Workflow:**
  654. 1. Set `otp_code` to a fresh 6-digit code from your authenticator and start the server.
  655. 2. On the first successful login, the server logs a warning line like:
  656. `nas1: 2FA bootstrap β€” copy this device_id into settings.json to skip OTP on future starts: <did>`
  657. Copy the `<did>` value.
  658. 3. Paste it into `device_id` and delete `otp_code`.
  659. 4. From now on, DSM treats this process as a trusted device β€” restarts, relogins after DSM error 119, and container-manager sessions all skip OTP.
  660. When `device_id` is present, it takes precedence over `otp_code` (trusted-device path). Legacy `.env` users can set the one-shot `SYNOLOGY_OTP_CODE` env var; for persistent `device_id`, migrate to `settings.json` (long opaque token doesn't fit an env var cleanly).
  661. ## πŸ“– Usage Examples
  662. ### πŸ“ File Operations
  663. #### βœ… Creating Files and Directories
  664. ![File Creation](assets/add.png)
  665. ```json
  666. // List directory
  667. {
  668. "path": "/volume1/homes"
  669. }
  670. // Search for PDFs
  671. {
  672. "path": "/volume1/documents",
  673. "pattern": ".pdf"
  674. }
  675. // Create new file
  676. {
  677. "path": "/volume1/documents/notes.txt",
  678. "content": "My important notes\nLine 2 of notes",
  679. "overwrite": false
  680. }
  681. ```
  682. #### πŸ—‘οΈ Deleting Files and Directories
  683. ![File Deletion](assets/delete.png)
  684. ```json
  685. // Delete file or directory (auto-detects type)
  686. {
  687. "path": "/volume1/temp/old-file.txt"
  688. }
  689. // Move file
  690. {
  691. "source_path": "/volume1/temp/file.txt",
  692. "destination_path": "/volume1/archive/file.txt"
  693. }
  694. ```
  695. ### ⬇️ Download Management
  696. #### πŸ› οΈ Creating a Download Task
  697. ![Download Sample](assets/download_sample.png)
  698. ```json
  699. // Create download task
  700. {
  701. "uri": "https://example.com/file.zip",
  702. "destination": "/volume1/downloads"
  703. }
  704. // Pause tasks
  705. {
  706. "task_ids": ["dbid_123", "dbid_456"]
  707. }
  708. ```
  709. #### 🦦 Download Results
  710. ![Download Result](assets/download_result.png)
  711. ## ✨ Features
  712. - βœ… **Unified Entry Point** - Single `main.py` supports both stdio and WebSocket clients
  713. - βœ… **Environment Controlled** - Switch modes via `ENABLE_XIAOZHI` environment variable
  714. - βœ… **Multi-Client Support** - Simultaneous Claude/Cursor + Xiaozhi access
  715. - βœ… **Secure Authentication** - RSA encrypted password transmission
  716. - βœ… **Session Management** - Persistent sessions across multiple NAS devices
  717. - βœ… **Complete File Operations** - Create, delete, list, search, rename, move files with detailed metadata
  718. - βœ… **Directory Management** - Recursive directory operations with safety checks
  719. - βœ… **Download Station** - Complete torrent and download management
  720. - βœ… **Docker Support** - Easy containerized deployment
  721. - βœ… **Backward Compatible** - Existing configurations work unchanged
  722. - βœ… **Error Handling** - Comprehensive error reporting and recovery
  723. ## πŸ—οΈ Architecture
  724. ### File Structure
  725. ```
  726. mcp-server-synology/
  727. β”œβ”€β”€ main.py # 🎯 Unified entry point
  728. β”œβ”€β”€ src/
  729. β”‚ β”œβ”€β”€ mcp_server.py # Standard MCP server
  730. β”‚ β”œβ”€β”€ multiclient_bridge.py # Multi-client bridge
  731. β”‚ β”œβ”€β”€ auth/ # Authentication modules
  732. β”‚ β”œβ”€β”€ filestation/ # File operations
  733. β”‚ └── downloadstation/ # Download management
  734. β”œβ”€β”€ docker-compose.yml # Single service, environment-controlled
  735. β”œβ”€β”€ Dockerfile
  736. β”œβ”€β”€ pyproject.toml # Dependencies (single source of truth)
  737. └── .env # Configuration
  738. ```
  739. ### Mode Selection
  740. - **`ENABLE_XIAOZHI=false`** β†’ `main.py` β†’ `mcp_server.py` (stdio only)
  741. - **`ENABLE_XIAOZHI=true`** β†’ `main.py` β†’ `multiclient_bridge.py` β†’ `mcp_server.py` (both clients)
  742. **Perfect for any workflow - from simple Claude/Cursor usage to advanced multi-client setups!** πŸš€

Ratings and comments

Sign in to rate this skill.

Sign in

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