Manage files and downloads on Synology NAS devices using an AI assistant.
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!
# Clone repository
git clone https://github.com/atom2ueki/mcp-server-synology.git
cd mcp-server-synology
# Create environment file
cp env.example .env
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/
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
# Install dependencies
pip install -r requirements.txt
# Run with environment control
python main.py
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"
}
}
}
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"
}
}
}
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"
}
}
}
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"
}
}
}
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"
}
}
}
}
New unified architecture supports both clients simultaneously!
ENABLE_XIAOZHI=true
XIAOZHI_TOKEN=your_xiaozhi_token_here
# Same command, different behavior based on environment
python main.py
# OR
docker-compose up
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!
synology_status
- Check authentication status and active sessionssynology_login
- Authenticate with Synology NAS (conditional)synology_logout
- Logout from session (conditional)list_shares
- List all available NAS shareslist_directory
- List directory contents with metadata
path
(required): Directory path starting with /
get_file_info
- Get detailed file/directory information
path
(required): File path starting with /
search_files
- Search files matching pattern
path
(required): Search directorypattern
(required): Search pattern (e.g., *.pdf
)create_file
- Create new files with content
path
(required): Full file path starting with /
content
(optional): File content (default: empty string)overwrite
(optional): Overwrite existing files (default: false)create_directory
- Create new directories
folder_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 directories
path
(required): Current file pathnew_name
(required): New filenamemove_file
- Move files to new location
source_path
(required): Source file pathdestination_path
(required): Destination pathoverwrite
(optional): Overwrite existing filesds_get_info
- Get Download Station informationds_list_tasks
- List all download tasks with status
offset
(optional): Pagination offsetlimit
(optional): Max tasks to returnds_create_task
- Create new download task
uri
(required): Download URL or magnet linkdestination
(optional): Download folder pathds_pause_tasks
- Pause download tasks
task_ids
(required): Array of task IDsds_resume_tasks
- Resume paused tasks
task_ids
(required): Array of task IDsds_delete_tasks
- Delete download tasks
task_ids
(required): Array of task IDsforce_complete
(optional): Force delete completedds_get_statistics
- Get download/upload statisticsVariable | 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
// 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
}
// 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"
}
// Create download task
{
"uri": "https://example.com/file.zip",
"destination": "/volume1/downloads"
}
// Pause tasks
{
"task_ids": ["dbid_123", "dbid_456"]
}
main.py
supports both stdio and WebSocket clientsENABLE_XIAOZHI
environment variablemcp-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
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! š
Batch convert PNG, JPG, and JPEG images to WebP format with options for quality, lossless mode, and multi-threaded processing.
Fast Windows file search using Everything SDK
Securely browse and read files within an Android project, with built-in validation and access controls for sensitive directories.
A read-only MCP server for querying live FTP data using the CData JDBC Driver.
Visualize directory structures with real-time updates, configurable depth, and smart exclusions for efficient project navigation.
Perform filesystem operations within specified directories.
A server for performing filesystem operations such as reading/writing files, managing directories, and searching.
Convert files between various formats, including images, documents, audio, video, and more.
A secure server for filesystem operations with controlled access to specified directories.
A high-performance MCP server for comprehensive JSON file operations, including reading, writing, and advanced querying, optimized for LLM interactions.