This MCP server for Synology NAS provides a unified backend that exposes a suite of MCP tools to manage files, downloads, and NAS sessions through a single server. It supports Claude/Cursor (stdin/stdout) as well as Xiaozhi (WebSocket) clients simultaneously. When enabled, Xiaozhi can access all available MCP tools via a WebSocket connection, while Claude/Cursor communicates over standard I/O. The server uses environment-controlled configuration to authenticate with the Synology NAS and to toggle the Xiaozhi bridge. You can run the server via Docker (docker-compose in practice) or directly with Python, depending on your deployment preference.

Once running, you can use the Available MCP Tools to perform authentication, file system operations, download management, and health monitoring against your Synology NAS. Tools include listing NAS shares, listing directories, creating files/directories, moving and renaming files, and managing Download Station tasks, among many other capabilities. The Xiaozhi bridge ensures WebSocket clients remain in sync and can reconnect automatically on drops, while Claude/Cursor clients operate through standard input/output without requiring WebSocket support.

Prerequisites:

• Docker and Docker Compose (recommended) or Python 3.8+ with pip
• Access to a Synology NAS with DSM running and API enabled
• Node.js is not required for this deployment (this MCP server is Docker/Python-friendly)

Install steps (Docker-based):

1. Clone the repository git clone https://github.com/atom2ueki/mcp-server-synology.git cd mcp-server-synology

2. Prepare environment

   • Create a .env file based on env.example and fill required fields: SYNOLOGY_URL=http://<nas-ip>:5000 SYNOLOGY_USERNAME=<your_username> SYNOLOGY_PASSWORD=<your_password> AUTO_LOGIN=true VERIFY_SSL=false ENABLE_XIAOZHI=true|false XIAOZHI_TOKEN=<token_if_applicable> XIAOZHI_MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/

3. Run with Docker (recommended) docker-compose up -d

   To build before run (if you have a Dockerfile in place)

   docker-compose up -d --build

4. Optional: Run directly with Python (without Docker) pip install -r requirements.txt export SYNOLOGY_URL=http://<nas-ip>:5000 export SYNOLOGY_USERNAME=<your_username> export SYNOLOGY_PASSWORD=<your_password> export AUTO_LOGIN=true export VERIFY_SSL=false export ENABLE_XIAOZHI=true|false export XIAOZHI_TOKEN=<token_if_applicable> python main.py

Prerequisites overview:

• Docker or Python environment ready on the host
• Access credentials for the Synology NAS
• Optional Xiaozhi token and endpoint if you want WebSocket support

Tips and notes:

• If ENABLE_XIAOZHI is true, ensure the Xiaozhi token and endpoint are valid; otherwise the bridge may fail to connect.
• VERIFY_SSL can be set to false in development environments to bypass SSL verification (not recommended in production).
• For Claude/Cursor users, the server communicates via stdio; for Xiaozhi users, it communicates via WebSocket.
• When using Docker, you can reuse docker-compose.yml to manage the multi-container setup; ensure the docker-compose file maps the proper environment variables and volumes if needed.
• If you encounter authentication errors with Synology, verify the NAS URL, credentials, and that the user has API access enabled.
• Logs are helpful: check docker logs <container> or tail the Python process logs to diagnose connectivity or authentication issues.