<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cmeans/mcp-synology/main/src/mcp_synology/icons/mcp-synology-logo-dark.svg" width="128"> <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/cmeans/mcp-synology/main/src/mcp_synology/icons/mcp-synology-logo-light.svg" width="128"> <img src="https://raw.githubusercontent.com/cmeans/mcp-synology/main/src/mcp_synology/icons/mcp-synology-logo-light.svg" alt="mcp-synology logo" width="128"> </picture> </p>

mcp-synology

MCP server for Synology NAS devices. Exposes Synology DSM API functionality as MCP tools that Claude can use.

<!-- mcp-name: io.github.cmeans/mcp-synology -->

Migrating from synology-mcp

If you're upgrading from synology-mcp (v0.3.x or earlier), the package has been renamed. A migration script handles config, state, keyring entries, and Claude Desktop config automatically:

# Download and run the migration script
curl -O https://raw.githubusercontent.com/cmeans/mcp-synology/main/scripts/migrate-from-synology-mcp.py
python migrate-from-synology-mcp.py          # dry run — preview changes
python migrate-from-synology-mcp.py --apply  # apply changes

The script migrates:

• Config directory (~/.config/synology-mcp/ → ~/.config/mcp-synology/)
• State directory (~/.local/state/synology-mcp/ → ~/.local/state/mcp-synology/)
• Keyring credentials
• Claude Desktop claude_desktop_config.json (updates command and paths)

See CHANGELOG.md for full details on breaking changes.

Supported Modules

File Station

Browse, search, transfer, and manage files on your NAS. 14 tools across two permission tiers:

• READ — list_shares, list_files, list_recycle_bin, search_files, get_file_info, get_dir_size, download_file
• WRITE — create_folder, rename, copy_files, move_files, delete_files, restore_from_recycle_bin, upload_file

System

Monitor NAS health and resource utilization. 2 read-only tools:

• get_system_info — model, firmware version, RAM, temperature, uptime (works for all users)
• get_resource_usage — live CPU load, memory usage, disk I/O, network throughput (requires admin account)

Download Station

Manage the Download Station queue and settings. 12 tools across two permission tiers:

• READ — list_downloads, get_download_info, get_download_stats, get_download_config, get_schedule
• WRITE — create_download, delete_download, pause_download, resume_download, edit_download, set_download_config, set_schedule

Download Station is opt-in: mcp-synology setup only configures File Station. To turn it on:

1. Install Download Station on the NAS from Package Center, if it isn't installed already. Without the package the tools still appear, but every call fails with api_not_found.

2. Edit your config file. That's ~/.config/mcp-synology/config.yaml, or the per-NAS file such as home-nas.yaml if you use Multi-NAS. Add downloadstation inside the existing modules: section; don't add a second modules: key. Use permission: read for the read tools only, or permission: write for all 12:

   modules:
     filestation:          # already there
       enabled: true
       permission: write
     downloadstation:      # add this
       enabled: true
       permission: write   # or read
   

3. Check the config: mcp-synology check --config <your config file> reports YAML or validation mistakes and confirms the login still works.

4. Restart your MCP client (for example, Claude Desktop). The server reads its config only at startup. The Download Station tools (list_downloads and the rest) then appear alongside the File Station ones. Ask the assistant to "list my downloads" to try it.

If the account isn't an admin, read Accounts below first: a non-admin needs a one-time setup step before Download Station will run its tasks.

Accounts. An admin (Download Station manager) can use every tool. A non-admin account needs the Download Station application privilege (Control Panel → User & Group → [account] → Edit → Applications). It also has these limits, all enforced or reported by the tools:

• First-time setup. Download Station doesn't start a non-admin's tasks until that user has a default destination; until then they wait forever. A user who has never opened Download Station has none. Set it once with set_download_config(default_destination="<share>"), which DSM applies to that user only. Until then, create_download with an explicit destination still creates the task but warns that it won't start. Without a destination, it refuses and says what to set. That refusal applies to any account, admin included, whenever there's no default destination to fall back on.
• Own tasks only. list_downloads and the other task tools see only the user's own tasks.
• Settings. get_download_config shows the user's own view, not the NAS-wide settings. set_download_config can change only the user's own default_destination; the speed limits are NAS-wide and are refused, because DSM accepts and then silently ignores them from a non-admin.
• Schedule. The weekly plan and limited-speed rates in get_schedule / set_schedule need an admin. A non-admin can still turn the schedule on or off, and that switch is NAS-wide.

Known limits:

• create_download returns no task IDs for URLs that use username / password.
• edit_download changes only the destination.
• There is no way to pick individual files inside a torrent.
• BT search and RSS feeds are not supported yet.
• delete_download(force_complete=true) doesn't reliably keep partial data: DSM discarded unfinished HTTP downloads anyway. DSM also refuses it for finished tasks, and the tool reports those as not removed.

Tested against DSM 7.1 (Download Station 3.9-4627) and DSM 7.2.2 (Download Station 4.1-5012).

Features

• Interactive setup — guided configuration that creates your config, stores credentials, handles 2FA, and emits a Claude Desktop snippet
• Permission tiers — READ or WRITE per module, enforced at tool registration. A read-only connection tells the model which tools it withholds and how to enable them, so the model doesn't claim the server can't do it
• 2FA support — auto-detected; device token bootstrap with automatic silent re-auth
• Secure credentials — OS keyring integration that works transparently on macOS, Windows, and Linux (including from Claude Desktop). See docs/credentials.md.
• Multi-NAS — manage multiple NAS devices with separate configs, credentials, and state

Quick Start

1. Run setup

uvx mcp-synology setup

Requires uv. uvx downloads and runs the latest version automatically — no separate install step needed.

Setup will prompt for your NAS host, credentials, and preferences. If your account has 2FA enabled, it will prompt for an OTP code and store a device token for automatic future logins.

At the end, it prints a Claude Desktop JSON snippet ready to copy-paste.

2. Add to Claude Desktop

Copy the snippet from setup into your claude_desktop_config.json and restart Claude Desktop. It will look something like:

{
  "mcpServers": {
    "synology-nas": {
      "command": "uvx",
      "args": ["mcp-synology", "serve", "--config", "~/.config/mcp-synology/nas.yaml"]
    }
  }
}

The config file name (e.g., nas.yaml) also serves as a natural identifier for the connection — you can name it to match your NAS (e.g., home-nas.yaml, office-nas.yaml).

On Linux, the server auto-detects the D-Bus session socket for keyring access. If auto-detection fails, add "env": {"DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/<uid>/bus"} to the Claude Desktop config. The setup command includes this in the generated snippet.

3. Verify

uvx mcp-synology check                # Validates credentials work
uvx mcp-synology setup --list         # Shows all configured NAS instances

Alternative: global install

If you prefer a persistent install (avoids download on each invocation). Requires uv — install with curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or see the installation guide for other options.

uv tool install mcp-synology
mcp-synology setup
mcp-synology check

Alternative: env-var-only mode

No config file needed if SYNOLOGY_HOST is set. This is useful for Docker or CI environments:

{
  "mcpServers": {
    "synology": {
      "command": "uvx",
      "args": ["mcp-synology", "serve"],
      "env": {
        "SYNOLOGY_HOST": "192.168.1.100",
        "SYNOLOGY_USERNAME": "your_user",
        "SYNOLOGY_PASSWORD": "your_password"
      }
    }
  }
}

Or from the CLI:

SYNOLOGY_HOST=192.168.1.100 uvx mcp-synology check

2FA Support

mcp-synology fully supports DSM accounts with two-factor authentication. It's auto-detected — you don't need to configure anything special:

1. Bootstrap — mcp-synology setup detects 2FA, prompts for your OTP code, and