mcp-server-synology

💾 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!

📦 Install from PyPI

No need to clone the repository — install the package directly from PyPI:

# With pip
pip install mcp-server-synology

# Or with pipx (isolated environment)
pipx install mcp-server-synology

# Or with uv
uv tool install mcp-server-synology

This installs two equivalent commands: synology-mcp and mcp-server-synology.

For MCP clients, uvx is the simplest option — it downloads and caches the package automatically, no manual install or local clone required:

{
  "mcpServers": {
    "synology": {
      "command": "uvx",
      "args": ["mcp-server-synology"]
    }
  }
}

Configuration lives outside the package, so it works the same as a source checkout: create ~/.config/synology-mcp/settings.json as described in Configuration Options.

🚀 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/

.env is read at run time, never baked into the image — docker-compose.yml injects its entries as container environment variables via env_file, so the file itself is not present inside the container. It is optional: if you configure NASes with settings.json instead (recommended), you can skip this file entirely.

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 the package and its dependencies (from PyPI, or from a clone with 'pip install .')
pip install mcp-server-synology

# Run with environment control
python main.py

🔌 Client Setup

The examples below use Docker with a local clone of this repository. If you installed from PyPI, use the uvx configuration from Install from PyPI instead — it works for Claude Desktop, Cursor, Continue and Codeium alike, with no local paths to adjust.

🤖 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"
      }
    }
  }
}

🌐 Remote Streamable HTTP Deployment

By default the server speaks stdio, which means the MCP client has to spawn the process locally (or via a bridge such as SSH/docker exec). For setups where the NAS is remote (different machine from where Claude/Cursor runs), set MCP_HTTP=true and the server serves native Streamable HTTP from uvicorn in the same process — no mcp-proxy sidecar and no separate /sse endpoint. This makes it consumable by any MCP client that supports URL-based connectors — exactly like ha-mcp or other "remote" MCP servers.

Architecture

[Claude Desktop / Cursor / ...]
        │
        │ HTTPS (URL connector)
        ▼
[Reverse proxy: DSM / Nginx / Traefik / Caddy]
        │  (TLS termination + auth)
        │ HTTP localhost:8765
        ▼
[Docker container]
  └─ python main.py
       └─ uvicorn → Streamable HTTP at /mcp

Deploy

1. All dependencies come from pyproject.toml: mcp>=2.0.0 ships starlette, uvicorn, and sse-starlette, so the same image serves both stdio and Streamable HTTP — no extra build arg or separate requirements file.
2. Use the provided docker-compose.http.yml:

# Edit credentials in docker-compose.http.yml first
docker compose -f docker-compose.http.yml up -d --build
docker logs -f synology-mcp-http

You should see the server log Starting Streamable HTTP MCP server on http://0.0.0.0:8765/mcp and the auto-login succeed. uvicorn's own Uvicorn running on … banner is not printed at the compose file's defaults — it is INFO on the uvicorn.error logger, which the server pins to warning unless DEBUG=true.

Reverse proxy

Most MCP clients require HTTPS, so the HTTP endpoint must be fronted by a TLS-terminating reverse proxy. For DSM users, the built-in Login Portal → Reverse Proxy does the job:

• Source: HTTPS, hostname synology-mcp.example.com, port 443
• Destination: HTTP, localhost, port 8765
• Custom Headers: none required — Streamable HTTP is plain POST/GET on a single endpoint, not a WebSocket upgrade. The Create → WebSocket preset is harmless if you already apply it elsewhere (it sets Connection: upgrade only for real upgrade requests), but it is not what keeps a stream open

For Nginx, the equivalent is:

location / {
    proxy_pass http://localhost:8765;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    # Responses may stream as long-lived text/event-stream
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 24h;
}

Client configuration

In Claude Desktop (or any MCP client that supports remote connectors), add a custom connector pointing at:

https://synology-mcp.example.com/mcp

The path is whatever MCP_HTTP_PATH is set to (default /mcp). No command, no args, no local Python — just a URL.

Security

The server does not implement any application-level authentication — anything that can reach the HTTP endpoint can call every tool. It does enable the MCP SDK's DNS-rebinding protection, which rejects requests whose Host/Origin headers are not on an allowlist (MCP_HTTP_ALLOWED_HOSTS / MCP_HTTP_ALLOWED_ORIGINS, defaulting to loopback). Behind a reverse proxy set both, minding the differing formats — hosts are bare (synology-mcp.example.com), origins are scheme-qualified (https://synology-mcp.example.com), as in the commented examples in docker-compose.http.yml. That guards browsers against rebinding attacks; it is not authentication. Mitigations:

• Keep it on a private network or behind a VPN
• Leave the published port on loopback (docker-compose.http.yml binds 127.0.0.1:8765) so only a same-host reverse proxy can reach it
• Use the reverse proxy to enforce an IP allow-list
• Add Basic Auth / mTLS / OAuth2 proxy at the reverse proxy layer
• Use a dedicated low-privilege DSM user (already recommended in the security warning above)

🌟 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

1. Add to your .env file:

ENABLE_XIAOZHI=true
XIAOZHI_TOKEN=your_xiaozhi_token_here

2. 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 sessions
• synology_list_nas - List all configured NAS units from settings.json
• synology_login - Authenticate with Synology NAS (conditional)
• synology_logout - Logout from session (conditional)

📁 File System Operations

• list_shares - List all available NAS shares
• list_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 /
• get_file_content - Read strict UTF-8 text or lossless base64 content
  • path (required): File path starting with /
  • encoding (optional): text (default) or base64
  • max_bytes (optional): Maximum raw bytes to read (default 1 MiB, hard limit 8 MiB)
• search_files - Recursively search for files and folders by name
  • path (required): Search directory
  • pattern (required): Case-insensitive substring of the name (e.g., invoice, .pdf). Wildcards are not special — DSM matches report and *report* identically.
• create_file - Create new files with content