synology MCP 工具

Install the package and its dependencies (from PyPI, or from a clone with 'pip install .')

pip install mcp-server-synology

📦 Install from PyPI

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

```bash

🚀 Quick Start with Docker

1️⃣ Setup Environment

```bash

3️⃣ Run with Docker

One simple command supports both modes:

```bash

Build and run

docker-compose up -d --build ```

🔌 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.

🌐 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.

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:

```bash

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.

Setup Steps

1. Add to your .env file:

ENABLE_XIAOZHI=true
XIAOZHI_TOKEN=your_xiaozhi_token_here

2. Run normally: ```bash

📖 Usage Examples

Or with pipx (isolated environment)

pipx install mcp-server-synology

Create environment file

cp env.example .env ```

2️⃣ Configure .env File

Basic Configuration (Claude/Cursor only): ```bash

Optional: Auto-login on startup

AUTO_LOGIN=true VERIFY_SSL=false

**Extended Configuration (Both Claude/Cursor + Xiaozhi):**

Optional: Auto-login on startup

AUTO_LOGIN=true VERIFY_SSL=false

Both Claude/Cursor + Xiaozhi mode (if ENABLE_XIAOZHI=true in .env)

docker-compose up -d

Run with environment control

python main.py ```

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.

Same command, different behavior based on environment

python main.py

⚙️ Configuration Options

⚠️ Security Warning: Use a Dedicated Account For this MCP server, create a dedicated Synology user account with appropriate permissions. This account should: - Have minimal required permissions only (not admin!) - Be used exclusively for MCP server automation - 2FA is now supported — if your DSM account has 2FA enabled, see the 2FA / OTP Accounts section below to supply an otp_code (one-shot) or device_id (persistent) field. Older guidance of "no 2FA" is no longer required.

Using settings.json (Recommended)

*Required for auto-login and default operations

Using settings.json (Multi-NAS Support)

For managing multiple Synology NAS devices, use the XDG standard config directory (~/.config/synology-mcp/settings.json):

mkdir -p ~/.config/synology-mcp
touch ~/.config/synology-mcp/settings.json
chmod 600 ~/.config/synology-mcp/settings.json  # Important: secure permissions!

Note: This follows the XDG Base Directory Specification - ~/.config/ is the standard location for user configuration files on Linux/macOS. You can customize the location by setting the XDG_CONFIG_HOME environment variable.

With Docker: The docker-compose.yml automatically mounts your ~/.config/synology-mcp directory into the container at /home/mcpuser/.config/synology-mcp, so multi-NAS works out of the box with Docker as well.

settings.json format:

{
  "synology": {
    "nas1": {
      "host": "192.168.1.100",
      "port": 5000,
      "username": "admin",
      "password": "your_password",
      "note": "Primary NAS at home"
    },
    "nas2": {
      "host": "192.168.1.200",
      "port": 5001,
      "username": "admin",
      "password": "your_password",
      "note": "Backup NAS"
    },
    "nas3": {
      "url": "https://nas.example.com",
      "username": "admin",
      "password": "your_password",
      "note": "NAS behind a reverse proxy"
    }
  },
  "xiaozhi": {
    "enabled": false,
    "token": "your_xiaozhi_token",
    "endpoint": "wss://api.xiaozhi.me/mcp/"
  },
  "server": {
    "auto_login": true,
    "verify_ssl": false,
    "session_timeout": 3600,
    "debug": false,
    "log_level": "INFO"
  }
}

Configuration fields: <div class="rdm-tbl-wrap"><table class="rdm-tbl"><thead><tr><th>Field</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>host</td><td>Yes*</td><td>NAS hostname or IP address</td></tr><tr><td>port</td><td>No</td><td>API port (default: 5000 for HTTP, 5001 for HTTPS)</td></tr><tr><td>url</td><td>Yes*</td><td>Full base URL (e.g., https://nas.example.com); wins over host/port — use for a NAS behind a reverse proxy</td></tr><tr><td>username</td><td>Yes</td><td>NAS username</td></tr><tr><td>password</td><td>Yes</td><td>NAS password</td></tr><tr><td>otp_code</td><td>No</td><td>One-shot 6-digit 2FA code (first login only, then remove)</td></tr><tr><td>device_id</td><td>No</td><td>Long-lived trusted-device token from DSM (did); skip OTP on all future logins</td></tr><tr><td>note</td><td>No</td><td>Optional description for your reference</td></tr></tbody></table></div>

*Either host or url is required per NAS entry.

Notes: - The server will use port 5001 (HTTPS) if port is 5001, otherwise defaults to HTTP (5000) - The host/port form always appends a port and derives the scheme from it, so it cannot express https://nas.example.com on the default 443 — set url directly for reverse-proxied setups - File permissions: chmod 600 ~/.config/synology-mcp/settings.json is required for security - The server will refuse to load settings if permissions are too open - Both .env and settings.json can be used together (settings.json takes priority)

🌟 Xiaozhi Integration

New unified architecture supports both clients simultaneously!

4️⃣ Alternative: Local Python

```bash

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

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