mcp-synology

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

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)

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
• 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 stores a device token in the keyring
2. Silent re-auth — subsequent logins use the device token automatically (no OTP prompts)
3. Per-instance — each NAS config gets its own device token, so mixed 2FA/non-2FA setups work fine

Device tokens persist until you explicitly revoke them in DSM (Personal > Security > Sign-in Activity). They do not expire on their own. If a token is revoked, run mcp-synology setup again to re-bootstrap.

Keyring & Credentials

Credentials are stored in the OS keyring and accessed transparently:

Credential resolution order: env vars > config file > keyring. Explicit sources override the implicit default.

For environments without a keyring (Docker, CI), use environment variables or inline credentials in the config file.

See docs/credentials.md for keyring service names, multi-NAS setup, and how to inspect/remove stored credentials.

Updates

mcp-synology checks for updates and notifies you in your Claude Desktop conversation — the first tool response in each session will include a notice if a newer version is available on PyPI.

To manage updates from the CLI:

mcp-synology --check-update                 # Check for a newer version
mcp-synology --auto-upgrade enable           # Auto-upgrade on each interactive run
mcp-synology --revert                        # Roll back to previous version
mcp-synology --revert 0.1.0                  # Roll back to a specific version

To disable update notifications, add to your config (top level):

# ~/.config/mcp-synology/config.yaml
check_for_updates: false

Configuration