synology MCP 工具

Install dependencies

pip install -r requirements.txt

🚀 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

🌐 Remote HTTP/SSE Deployment (NEW)

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), you can expose the MCP server over HTTP/SSE using mcp-proxy. This makes it consumable by any MCP client that supports URL-based connectors — exactly like ha-mcp or other "remote" MCP servers.

Deploy

1. mcp-proxy is installed automatically when you build the HTTP image — it lives in requirements-http.txt and the provided compose file sets the INSTALL_HTTP=true build arg (it is not in the default stdio/Xiaozhi image). 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 mcp-proxy report Uvicorn running on http://0.0.0.0:8765 and the auto-login succeed.

Setup Steps

1. Add to your .env file:

ENABLE_XIAOZHI=true
XIAOZHI_TOKEN=your_xiaozhi_token_here

2. Run normally: ```bash

📖 Usage Examples

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

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: - NOT have 2FA enabled - The MCP server cannot handle 2FA prompts and will fail authentication - Have minimal required permissions only (not admin!) - Be used exclusively for MCP server automation Using your primary account with 2FA is dangerous - if auto-login fails, you may be locked out of your NAS!

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"
    }
  },
  "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>username</td><td>Yes</td><td>NAS username</td></tr><tr><td>password</td><td>Yes</td><td>NAS password</td></tr><tr><td>note</td><td>No</td><td>Optional description for your reference</td></tr></tbody></table></div>

Notes: - The server will use port 5001 (HTTPS) if port is 5001, otherwise defaults to HTTP (5000) - 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"
      }
    }
  }
}