Synology MCP Server

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

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

Related MCP server: Syncthing MCP Server

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

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:

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

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.