💾 Synology MCP Server
A Model Context Protocol (MCP) server for Synology NAS devices. Enables AI assistants to manage files and downloads through secure authentication and session management.
🌟 NEW: Unified server supports both Claude/Cursor (stdio) and Xiaozhi (WebSocket) simultaneously!
🚀 Quick Start with Docker
1️⃣ Setup Environment
# Clone repository
git clone https://github.com/atom2ueki/mcp-server-synology.git
cd mcp-server-synology
# Create environment file
cp env.example .env
2️⃣ Configure .env File
Basic Configuration (Claude/Cursor only):
# Required: Synology NAS connection
SYNOLOGY_URL=http://192.168.1.100:5000
SYNOLOGY_USERNAME=your_username
SYNOLOGY_PASSWORD=your_password
# Optional: Auto-login on startup
AUTO_LOGIN=true
VERIFY_SSL=false
Extended Configuration (Both Claude/Cursor + Xiaozhi):
# Required: Synology NAS connection
SYNOLOGY_URL=http://192.168.1.100:5000
SYNOLOGY_USERNAME=your_username
SYNOLOGY_PASSWORD=your_password
# Optional: Auto-login on startup
AUTO_LOGIN=true
VERIFY_SSL=false
# Enable Xiaozhi support
ENABLE_XIAOZHI=true
XIAOZHI_TOKEN=your_xiaozhi_token_here
XIAOZHI_MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/
3️⃣ Run with Docker
One simple command supports both modes:
# Claude/Cursor only mode (default if ENABLE_XIAOZHI not set)
docker-compose up -d
# Both Claude/Cursor + Xiaozhi mode (if ENABLE_XIAOZHI=true in .env)
docker-compose up -d
# Build and run
docker-compose up -d --build
4️⃣ Alternative: Local Python
# Install dependencies
pip install -r requirements.txt
# Run with environment control
python main.py
🔌 Client Setup
🤖 Claude Desktop
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"synology": {
"command": "docker-compose",
"args": [
"-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
"run", "--rm", "synology-mcp"
],
"cwd": "/path/to/your/mcp-server-synology"
}
}
}
↗️ Cursor
Add to your Cursor MCP settings:
{
"mcpServers": {
"synology": {
"command": "docker-compose",
"args": [
"-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
"run", "--rm", "synology-mcp"
],
"cwd": "/path/to/your/mcp-server-synology"
}
}
}
🔄 Continue (VS Code Extension)
Add to your Continue configuration (.continue/config.json):
{
"mcpServers": {
"synology": {
"command": "docker-compose",
"args": [
"-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
"run", "--rm", "synology-mcp"
],
"cwd": "/path/to/your/mcp-server-synology"
}
}
}
💻 Codeium
For Codeium's MCP support:
{
"mcpServers": {
"synology": {
"command": "docker-compose",
"args": [
"-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
"run", "--rm", "synology-mcp"
],
"cwd": "/path/to/your/mcp-server-synology"
}
}
}
🐍 Alternative: Direct Python Execution
If you prefer not to use Docker:
{
"mcpServers": {
"synology": {
"command": "python",
"args": ["main.py"],
"cwd": "/path/to/your/mcp-server-synology",
"env": {
"SYNOLOGY_URL": "http://192.168.1.100:5000",
"SYNOLOGY_USERNAME": "your_username",
"SYNOLOGY_PASSWORD": "your_password",
"AUTO_LOGIN": "true",
"ENABLE_XIAOZHI": "false"
}
}
}
}
🌟 Xiaozhi Integration
New unified architecture supports both clients simultaneously!
How It Works
- ENABLE_XIAOZHI=false (default): Standard MCP server for Claude/Cursor via stdio
- ENABLE_XIAOZHI=true: Multi-client bridge supporting both:
- 📡 Xiaozhi: WebSocket connection
- 💻 Claude/Cursor: stdio connection
Setup Steps
- Add to your .env file:
ENABLE_XIAOZHI=true
XIAOZHI_TOKEN=your_xiaozhi_token_here
- Run normally:
# Same command, different behavior based on environment
python main.py
# OR
docker-compose up
Key Features
- ✅ Zero Configuration Conflicts: One server, multiple clients
- ✅ Parallel Operation: Both clients can work simultaneously
- ✅ All Tools Available: Xiaozhi gets access to all Synology MCP tools
- ✅ Backward Compatible: Existing setups work unchanged
- ✅ Auto-Reconnection: Handles WebSocket connection drops
- ✅ Environment Controlled: Simple boolean flag to enable/disable
Startup Messages
Claude/Cursor only mode:
🚀 Synology MCP Server
==============================
📌 Claude/Cursor only mode (ENABLE_XIAOZHI=false)
Both clients mode:
🚀 Synology MCP Server with Xiaozhi Bridge
==================================================
🌟 Supports BOTH Xiaozhi and Claude/Cursor simultaneously!
🛠️ Available MCP Tools
🔐 Authentication
synology_status- Check authentication status and active sessionssynology_login- Authenticate with Synology NAS (conditional)synology_logout- Logout from session (conditional)
📁 File System Operations
list_shares- List all available NAS shareslist_directory- List directory contents with metadatapath(required): Directory path starting with/
get_file_info- Get detailed file/directory informationpath(required): File path starting with/
search_files- Search files matching patternpath(required): Search directorypattern(required): Search pattern (e.g.,*.pdf)
create_file- Create new files with contentpath(required): Full file path starting with/content(optional): File content (default: empty string)overwrite(optional): Overwrite existing files (default: false)
create_directory- Create new directoriesfolder_path(required): Parent directory path starting with/name(required): New directory nameforce_parent(optional): Create parent directories if needed (default: false)
delete- Delete files or directories (auto-detects type)path(required): File/directory path starting with/
rename_file- Rename files or directoriespath(required): Current file pathnew_name(required): New filename
move_file- Move files to new locationsource_path(required): Source file pathdestination_path(required): Destination pathoverwrite(optional): Overwrite existing files
📥 Download Station Management
ds_get_info- Get Download Station informationds_list_tasks- List all download tasks with statusoffset(optional): Pagination offsetlimit(optional): Max tasks to return
ds_create_task- Create new download taskuri(required): Download URL or magnet linkdestination(optional): Download folder path
ds_pause_tasks- Pause download taskstask_ids(required): Array of task IDs
ds_resume_tasks- Resume paused taskstask_ids(required): Array of task IDs
ds_delete_tasks- Delete download taskstask_ids(required): Array of task IDsforce_complete(optional): Force delete completed
ds_get_statistics- Get download/upload statistics
⚙️ Configuration Options
| Variable | Required | Default | Description |
|---|---|---|---|
SYNOLOGY_URL |
Yes* | - | NAS base URL (e.g., http://192.168.1.100:5000) |
SYNOLOGY_USERNAME |
Yes* | - | Username for authentication |
SYNOLOGY_PASSWORD |
Yes* | - | Password for authentication |
AUTO_LOGIN |
No | true |
Auto-login on server start |
VERIFY_SSL |
No | true |
Verify SSL certificates |
DEBUG |
No | false |
Enable debug logging |
ENABLE_XIAOZHI |
No | false |
Enable Xiaozhi WebSocket bridge |
XIAOZHI_TOKEN |
Xiaozhi only | - | Authentication token for Xiaozhi |
XIAOZHI_MCP_ENDPOINT |
No | wss://api.xiaozhi.me/mcp/ |
Xiaozhi WebSocket endpoint |
*Required for auto-login and default operations
📖 Usage Examples
📁 File Operations
✅ Creating Files and Directories
// List directory
{
"path": "/volume1/homes"
}
// Search for PDFs
{
"path": "/volume1/documents",
"pattern": "*.pdf"
}
// Create new file
{
"path": "/volume1/documents/notes.txt",
"content": "My important notes\nLine 2 of notes",
"overwrite": false
}
🗑️ Deleting Files and Directories
// Delete file or directory (auto-detects type)
{
"path": "/volume1/temp/old-file.txt"
}
// Move file
{
"source_path": "/volume1/temp/file.txt",
"destination_path": "/volume1/archive/file.txt"
}
⬇️ Download Management
🛠️ Creating a Download Task
// Create download task
{
"uri": "https://example.com/file.zip",
"destination": "/volume1/downloads"
}
// Pause tasks
{
"task_ids": ["dbid_123", "dbid_456"]
}
🦦 Download Results
✨ Features
- ✅ Unified Entry Point - Single
main.pysupports both stdio and WebSocket clients - ✅ Environment Controlled - Switch modes via
ENABLE_XIAOZHIenvironment variable - ✅ Multi-Client Support - Simultaneous Claude/Cursor + Xiaozhi access
- ✅ Secure Authentication - RSA encrypted password transmission
- ✅ Session Management - Persistent sessions across multiple NAS devices
- ✅ Complete File Operations - Create, delete, list, search, rename, move files with detailed metadata
- ✅ Directory Management - Recursive directory operations with safety checks
- ✅ Download Station - Complete torrent and download management
- ✅ Docker Support - Easy containerized deployment
- ✅ Backward Compatible - Existing configurations work unchanged
- ✅ Error Handling - Comprehensive error reporting and recovery
🏗️ Architecture
File Structure
mcp-server-synology/
├── main.py # 🎯 Unified entry point
├── src/
│ ├── mcp_server.py # Standard MCP server
│ ├── multiclient_bridge.py # Multi-client bridge
│ ├── auth/ # Authentication modules
│ ├── filestation/ # File operations
│ └── downloadstation/ # Download management
├── docker-compose.yml # Single service, environment-controlled
├── Dockerfile
├── requirements.txt
└── .env # Configuration
Mode Selection
ENABLE_XIAOZHI=false→main.py→mcp_server.py(stdio only)ENABLE_XIAOZHI=true→main.py→multiclient_bridge.py→mcp_server.py(both clients)
Perfect for any workflow - from simple Claude/Cursor usage to advanced multi-client setups! 🚀
Metadata
Release files for iflow-mcp_atom2ueki-mcp-server-synology 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_atom2ueki_mcp_server_synology-0.1.0.tar.gz | 2.6 MB | Without provenance | Details for iflow_mcp_atom2ueki_mcp_server_synology-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_atom2ueki_mcp_server_synology-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_atom2ueki_mcp_server_synology-0.1.0-py3-none-any.whl |
Total release size: 2.6 MB
Release files / iflow_mcp_atom2ueki_mcp_server_synology-0.1.0.tar.gz
| Download URL | iflow_mcp_atom2ueki_mcp_server_synology-0.1.0.tar.gz |
|---|---|
| Size | 2.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
afc4183b6e37e73c4df42ae2fe4d501ff4faac30721c9ab8f8905f272a73e6dc
|
|
BLAKE2b-256 checksum How to use checksums |
80d65e9938c4d2795d37bd235e14f0c08a80bae7d73532416180dc7339049782
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_atom2ueki_mcp_server_synology-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_atom2ueki_mcp_server_synology-0.1.0-py3-none-any.whl |
|---|---|
| Size | 35.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dc32327503c4251252dff39ba3314222e80b41515715c4c0f81b952387717935
|
|
BLAKE2b-256 checksum How to use checksums |
ee668fc02838b3c10e3b65fcdf85f6ad687d452588cf41cd3a309374c11c1204
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_atom2ueki-mcp-server-synology 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.