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 ha

... View full README on GitHub