<div align="center">

<img src="docs/assets/banner.svg" alt="Synology MCP Server" width="100%" />

Synology MCP Server

Monitor and manage a Synology DSM 7 NAS from any MCP client — and build live dashboards right inside the chat.

</div>

A Model Context Protocol (MCP) server that gives an LLM client such as Claude 71 tools to monitor and manage a Synology DSM 7 NAS: system health, storage and disks, files, Docker, virtual machines, packages, DSM updates, Download Station, Hyper Backup, users, services, security, certificates and more — plus a one-call snapshot for rendering beautiful dashboards as artifacts.

It speaks the official DSM Web API (entry.cgi), handles login (including 2FA via a persistent trusted-device token), caches the session and re-authenticates automatically.

Tested on DSM 7.3.2 (DS423+). Most tools use stable core APIs and work across DSM 7.x.

---

Table of contents

• What is an MCP server?
• How it fits together
• Features
• Quick start
• Configuration
  • Environment variables
  • Two-factor authentication
• Connecting an MCP client
  • Claude Desktop
  • Claude Code
• Dashboards & the skill
• Usage examples
• Tool reference
• Architecture
• Security
• Troubleshooting
• FAQ
• Contributing
• License

---

What is an MCP server?

The Model Context Protocol (MCP) is an open standard that lets AI assistants talk to external tools and data sources in a uniform way. An MCP server exposes a set of tools (functions the model can call) over a simple protocol; an MCP client (the app you chat in, e.g. Claude Desktop) connects to the server and lets the model call those tools on your behalf.

Think of it as a universal adapter between the AI and your software: instead of the model guessing, it calls a real function that returns real data.

This project is an MCP server for your Synology NAS. It translates plain requests like “how full are my volumes?” or “restart the Home Assistant container” into authenticated calls to the Synology DSM API, and hands structured results back to the model — which then answers you or renders a dashboard.

You ──▶ Claude (MCP client) ──▶ Synology MCP server ──▶ DSM Web API ──▶ your NAS
                ▲                                                          │
                └──────────────  results / dashboard  ◀───────────────────┘

You don't need to know any of the API details — just install the server, point it at your NAS, connect your client, and ask in natural language.

How it fits together

flowchart LR
    U["👤 You"] -->|natural language| C["🤖 Claude<br/>(MCP client)"]
    C -->|tool call| S["⚙️ Synology MCP server<br/>71 tools"]
    S -->|HTTPS entry.cgi| D["🟦 Synology DSM 7 API"]
    D --> N["🗄️ Your NAS<br/>storage · docker · vms · users …"]
    N -->|JSON| S
    S -->|structured result| C
    C -->|answer or 📊 dashboard| U

The server authenticates once (with optional 2FA via a trusted-device token), caches the session, and re-authenticates automatically when it expires.

---

Features

• 71 tools across 21 domains — see the full Tool Reference.
• Monitoring: system info, CPU/RAM/network load, health, connections, processes.
• Storage: volumes, storage pools, per-disk S.M.A.R.T. and temperatures.
• Files: browse, search, info, directory size, MD5, create/rename/copy/move/delete, extract archives, public share links.
• Apps: Docker (containers, images, projects, logs, live stats, start/stop/restart), Virtual Machine Manager, Download Station, Hyper Backup, Task Scheduler, Surveillance Station (cameras), Synology Photos and Synology Drive.
• Administration: packages & DSM updates, users/groups, shared folders (create/delete), file services (SMB/AFP/NFS/FTP), SSH/SNMP, hardware/UPS, security, certificates, DDNS, QuickConnect, notifications, logs, security scan.
• Dashboards: get_overview returns a complete snapshot in one call; the bundled skill teaches the client to render it as a polished HTML dashboard.
• Safe by design: state-changing tools are tagged control; destructive power operations (reboot/shutdown/DSM update) are disabled unless explicitly enabled.
• No hard-coded secrets: all credentials come from environment variables / .env.

---

Quick start

Option A — guided setup (recommended)

One interactive script creates the environment, asks for your NAS details, handles 2FA, tests the connection and registers the server in Claude Desktop for you:

git clone https://github.com/rafalr100/synology-mcp.git
cd synology-mcp
python3 configure.py

Then fully quit and reopen Claude Desktop. That's it.

Option B — manual

# 1. Clone
git clone https://github.com/rafalr100/synology-mcp.git
cd synology-mcp

# 2. Install (uv recommended)
uv venv --python 3.12 .venv
uv pip install --python .venv -e .
#   …or:  python3 -m venv .venv && .venv/bin/pip install -e .

# 3. Configure
cp .env.example .env       # then edit URL / username / password

# 4. (only if your account uses 2FA) get a device token
.venv/bin/python bootstrap_2fa.py 123456     # 123456 = current OTP code

# 5. Verify
.venv/bin/python smoke_test.py

Then connect it to a client.

---

Configuration

Step 1 — Prepare the NAS

1. Find the NAS address & port. In DSM: Control Panel → Network → Network Interface (or your router). The default Web API port is 5000 (HTTP) / 5001 (HTTPS). Your URL will look like http://192.168.1.100:5000.
2. (Recommended) Create a dedicated user. Control Panel → User & Group → Create. Give it only the access it needs (the apps and shared folders you want to manage). Admin-group membership is required for some tools (storage, users, services, certificates, power).
3. 2FA? If the account uses two-factor auth, keep your authenticator app handy for Step 4. The DSM Web API itself is enabled by default — nothing else to turn on.

Step 2 — Create your .env

Copy .env.example to .env and fill it in:

SYNOLOGY_URL=http://192.168.1.100:5000
SYNOLOGY_USER=your_username
SYNOLOGY_PASS=your_password

Environment variables

Variable	Required	Default	Description
SYNOLOGY_URL	✅	http://localhost:5000	Base URL of the NAS (use https://…:5001 for TLS)
SYNOLOGY_USER	✅	—	DSM username
SYNOLOGY_PASS	✅	—	DSM password
SYNOLOGY_DEVICE_ID	2FA only	—	Trusted-device token (from bootstrap_2fa.py)
SYNOLOGY_OTP	—	—	One-time OTP (bootstrap only; prefer the device token)
SYNOLOGY_VERIFY_SSL	—	false	Verify the TLS certificate
SYNOLOGY_TIMEOUT	—	30	HTTP timeout (seconds)
SYNOLOGY_SESSION_NAME	—	SynologyMCP	Session name shown in DSM
SYNOLOGY_DEVICE_NAME	—	SynologyMCP	Device name shown in DSM
SYNOLOGY_ENABLE_POWER_CONTROL	—	false	Allow reboot_nas / shutdown_nas / install_dsm_update

See docs/CONFIGURATION.md for details.

Step 3 — How login works

flowchart TD
    A["Server starts"] --> B{"SYNOLOGY_DEVICE_ID set?"}
    B -->|yes| C["Login with password + device token"]
    B -->|no| E{"SYNOLOGY_OTP set?"}
    E -->|yes| F["Login with password + OTP (one-off)"]
    E -->|no| G["Login with password only"]
    C --> H["✅ Session cached"]
    F --> H
    G --> H
    H --> I["Auto re-login if the session expires"]

Two-factor authentication (2FA)

If your account has 2FA enabled, a password alone cannot log in. Exchange one OTP code for a persistent trusted-device token (so you never need an OTP again):

.venv/bin/python bootstrap_2fa.py 123456     # current 6-digit code from your authenticator

This appends SYNOLOGY_DEVICE_ID=… to your .env. If the token is ever invalidated (e.g. after a password change), simply run the bootstrap again.

---

Connecting an MCP client

The server runs locally and talks to your NAS over the LAN. It works with local clients (Claude Desktop, Claude Code). It is not reachable from the claude.ai web app, whose cloud servers cannot see your local network.

Claude Desktop

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "synology": {
      "command": "/absolute/path/to/synology-mcp/.venv/bin/python",
      "args": ["-m", "synology_mcp"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/synology-mcp",
        "SYNOLOGY_URL": "http://192.168.1.100:5000",
        "SYNOLOGY_USER": "your_username",
        "SYNOLOGY_PASS": "your_password",
        "SYNOLOGY_DEVICE_ID": "your_device_token_if_2fa"
      }
    }
  }
}

Fully quit and reopen Claude Desktop — the Synology tools then appear in the tools menu. A ready-to-edit copy lives in examples/claude_desktop_config.example.json.

Claude Code

claude mcp add synology -- /absolute/path/to/synology-mcp/.venv/bin/python -m synology_mcp

…or drop a project-scoped .mcp.json in your working directory.

Tip: keep credentials only in .env — the server auto-loads it from its own directory, so you can omit the env block in the client config.

---

Dashboards & the skill

Ask the client for “a dashboard of my NAS” and it will call get_overview (one round-trip returning system, load, storage, disks and workload counts) and render a self-contained HTML dashboard as an artifact.

The repo ships a Claude skill (skills/synology-nas/SKILL.md) that teaches the client when to use which tool and how to render dashboards — including a design guide and an HTML template. See docs/DASHBOARDS.md.

---

Usage examples

Natural-language prompts you can use once connected:

• “Give me an overview / dashboard of my NAS.”
• “How full are my volumes, and are all disks healthy?”
• “Is a DSM update available? Which Docker images can be updated?”
• “Show running containers and restart homeassistant.” (asks to confirm)
• “List virtual machines and their state.”
• “What’s connected right now, and show the last 10 system log entries.”
• “Search /home for *.pdf and tell me the size of /docker.”
• “Are SSH and SMB enabled? What’s my DDNS hostname and certificate expiry?”

More in examples/prompts.md.

---

Tool reference

All 71 tools are documented — with parameters and what each returns — in docs/TOOLS.md. Summary by domain:

Domain	Tools
Dashboard	get_overview
System monitoring	get_system_info, get_resource_usage, get_network_info, get_resource_history
Health & activity	get_system_health, get_active_connections, list_processes, get_time_settings
Storage	get_storage_info, get_storage_pools, get_disk_info
Files	list_shares, list_files, get_file_info, get_directory_size, get_file_md5, search_files, create_folder, rename_item, copy_move_item, delete_item, extract_archive, create_share_link
Packages & updates	check_dsm_update, list_packages, set_package_state
Docker	list_containers, get_container_logs, get_container_stats, list_docker_projects, list_docker_images, set_container_state
Virtual machines	list_virtual_machines, set_vm_state
Surveillance Station	get_surveillance_info, list_cameras
Synology Photos	list_photo_albums
Synology Drive	list_drive_connections
Download Station	list_downloads, add_download, manage_download
Backup	list_backup_tasks, run_backup_task
Task Scheduler	list_scheduled_tasks, run_scheduled_task
Users & shares	list_users, list_groups, list_shared_folders, create_shared_folder, delete_shared_folder
Services	get_file_services, set_file_service, get_terminal_settings, get_snmp_settings
Hardware	get_power_settings, get_hibernation_settings, get_ups_status, list_usb_devices
Security	get_security_settings, get_autoblock_settings, get_firewall_status, list_certificates
Network services	get_ddns_status, get_quickconnect_status
Notifications	get_notification_settings
Logs & scan	get_system_logs, get_security_scan_status
Power (opt-in)	reboot_nas, shutdown_nas, install_dsm_update

---

Architecture

synology_mcp/
├── config.py          # settings from env / .env (no hard-coded secrets)
├── api.py             # async DSM client: login, 2FA, session, auto-reauth
├── app.py             # shared FastMCP instance + formatting helpers
├── server.py          # entry point (python -m synology_mcp)
└── tools/             # one module per domain; importing registers the tools
    ├── dashboard.py      monitoring.py   system.py     storage.py
    ├── files.py          packages.py     docker.py     virtualization.py
    ├── downloads.py      backup.py       scheduler.py  admin.py
    ├── services.py       hardware.py     security.py   network_services.py
    ├── notifications.py  power.py
skills/synology-nas/   # Claude skill: tool guidance + dashboard rendering
docs/                  # TOOLS.md, CONFIGURATION.md, DASHBOARDS.md
examples/              # client config + example prompts

Every call goes through the DSM entry.cgi gateway; API versions were verified against a live DSM 7.3.2 system. Adding a tool: write an @mcp.tool() async function in a module under synology_mcp/tools/ and add the module to tools/__init__.py.

---

Security

• Credentials live in .env / client config, never in code. .env and .mcp.json are git-ignored.
• Prefer a dedicated DSM account with only the privileges you need over the main admin.
• Intended for trusted local-network use.
• Power operations are opt-in via SYNOLOGY_ENABLE_POWER_CONTROL=true.
• The HTTP client silences request logging so credentials never reach stderr.

---

Troubleshooting

Symptom	Cause / fix
auth failed (code 400)	Wrong username or password.
auth failed (code 403/406)	Account uses 2FA — run python bootstrap_2fa.py <OTP> to get a device token.
auth failed (code 400) after enabling 2FA	The OTP expired (30 s window) — re-run the bootstrap with a fresh code.
Synology API error (code 105)	Your account lacks permission for that action (use an admin account).
Synology API error (code 119)	Session expired — handled automatically; if it persists, restart the server.
Tools don’t appear in Claude Desktop	Fully quit (not just close) and reopen; check the config path and that the command path is absolute.
ModuleNotFoundError: synology_mcp	Set PYTHONPATH to the repo root in the client env, or pip install -e ..
Connection timeout	Check SYNOLOGY_URL/port and that the NAS is reachable; raise SYNOLOGY_TIMEOUT.
TLS certificate error	Use http://…:5000, or set SYNOLOGY_VERIFY_SSL=false (default) for self-signed certs.
A feature tool errors	That package/feature may not be installed/enabled (e.g. VMM, Docker, UPS, DDNS).

---

FAQ

Does this work with the claude.ai website or mobile app? No — those run in Anthropic’s cloud, which can’t reach a NAS on your LAN. Use a local client (Claude Desktop / Claude Code). For remote access you’d need a VPN (e.g. Tailscale) and a remote MCP transport, which is out of scope here.

Which DSM versions are supported? Built and tested on DSM 7.x (7.3.2). DSM 6 uses older API paths and is not supported.

Is it safe? Can it delete my data? Read tools are safe. State-changing tools are tagged control; a well-behaved client confirms before using them. Reboot/shutdown/update require an explicit opt-in flag.

Does it store my password? Only where you put it — in .env or the client config, both local to your machine.

Can I run it without 2FA? Yes. 2FA is optional; without it, username + password is enough.

---

Roadmap

Planned additions (Surveillance Station, Synology Photos & Drive, richer logs, time/NTP, and more) are tracked in docs/ROADMAP.md.

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md.

---

License

MIT.

Not affiliated with or endorsed by Synology Inc. “Synology” and “DSM” are trademarks of their respective owners.