💾 Synology MCP Server

💾 Synology MCP Server

适用于 Synology NAS 设备的模型上下文协议（MCP）服务。通过安全身份验证和会话管理，让 AI 助手能够管理文件和下载内容。

🌟 新功能：统一服务可同时支持 Claude/Cursor（stdio）和 Xiaozhi（WebSocket）！

📦 从 PyPI 安装

无需克隆代码仓库，直接从 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

此操作会安装两个功能相同的命令：synology-mcp 和 mcp-server-synology。

对于 MCP 客户端，uvx 是最简单的选择——它会自动下载并缓存软件包，无需手动安装或在本地克隆：

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

配置存储在软件包之外，因此其工作方式与从源代码检出时相同：按照配置选项中的说明，创建 ~/.config/synology-mcp/settings.json。

🚀 使用 Docker 快速开始

1️⃣ 设置环境

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

# Create environment file
cp env.example .env

2️⃣ 配置 .env 文件

基本配置（仅 Claude/Cursor）：

# 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

扩展配置（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 在运行时读取，不会被打包到镜像中——docker-compose.yml 通过 env_file 将其中的条目注入为容器环境变量，因此该文件本身不会存在于容器内。此文件为可选项：如果改用 settings.json 配置 NAS（推荐），则可以完全跳过此文件。

3️⃣ 使用 Docker 运行

一条简单命令即可支持两种模式：

# 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️⃣ 备选方案：本地 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

🔌 客户端设置

以下示例使用 Docker 和本地克隆的代码仓库。如果你从 PyPI 安装，请改用从 PyPI 安装中的 uvx 配置——该配置适用于 Claude Desktop、Cursor、Continue 和 Codeium，无需调整本地路径。

🤖 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件：

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

将以下内容添加到 Cursor MCP 设置：

{
  "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 扩展）

将以下内容添加到 Continue 配置（.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

Codeium 的 MCP 支持配置：

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

🐍 备选方案：直接使用 Python 执行

如果你不想使用 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"
      }
    }
  }
}

🌐 远程 Streamable HTTP 部署

默认情况下，服务使用 stdio 通信，这意味着 MCP 客户端必须在本地启动进程（或通过 SSH/docker exec 等桥接方式启动）。如果 NAS 位于远程（与运行 Claude/Cursor 的机器不同），请设置 MCP_HTTP=true，服务便会在同一进程中通过 uvicorn 提供原生 Streamable HTTP——无需 mcp-proxy 辅助服务，也无需单独的 /sse 端点。这样，任何支持基于 URL 连接器的 MCP 客户端都能使用该服务——与 ha-mcp 或其他“远程”MCP 服务完全一样。

架构

[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

部署

1. 所有依赖项均来自 pyproject.toml：mcp>=2.0.0 包含 starlette、uvicorn 和 sse-starlette，因此同一镜像可同时提供 stdio 和 Streamable HTTP 服务——无需额外的构建参数或单独的 requirements 文件。
2. 使用提供的 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

你应该会看到服务日志 Starting Streamable HTTP MCP server on http://0.0.0.0:8765/mcp，并且自动登录成功。按照 compose 文件的默认设置，不会显示 uvicorn 自带的 Uvicorn running on … 横幅——它属于 uvicorn.error 日志记录器的 INFO 级别，而服务会将其日志级别固定为 warning，除非设置了 DEBUG=true。

反向代理

大多数 MCP 客户端都要求使用 HTTPS，因此 HTTP 端点必须置于执行 TLS 终止的反向代理之后。对于 DSM 用户，内置的 登录门户 → 反向代理 即可满足需求：

• 来源：HTTPS，主机名 synology-mcp.example.com，端口 443
• 目标：HTTP，localhost，端口 8765
• 自定义标头：无需设置——Streamable HTTP 通过单个端点使用普通 POST/GET 请求，而非 WebSocket 升级。如果你已在其他地方使用 创建 → WebSocket 预设，则无需移除（它只会在实际升级请求中设置 Connection: upgrade），但它并不能保持流处于打开状态。

对于 Nginx，对应配置如下：

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;
}

客户端配置

在 Claude Desktop（或任何支持远程连接器的 MCP 客户端）中，添加一个指向以下地址的自定义连接器：

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

路径由 MCP_HTTP_PATH 的设置决定（默认为 /mcp）。无需 command、args 或本地 Python，只需一个 URL。

安全性

该服务没有实现任何应用层身份验证——任何能访问 HTTP 端点的对象都可以调用所有工具。它确实启用了 MCP SDK 的 DNS 重绑定保护机制，会拒绝 Host/Origin 标头不在允许列表中的请求（MCP_HTTP_ALLOWED_HOSTS / MCP_HTTP_ALLOWED_ORIGINS，默认值为 loopback）。在反向代理后使用时，请设置这两个变量，并注意它们的格式不同：主机名不带协议（synology-mcp.example.com），来源则需要包含协议（https://synology-mcp.example.com），可参考 docker-compose.http.yml 中注释掉的示例。这能防止浏览器遭受重绑定攻击，但不是身份验证。缓解措施：

• 将其部署在专用网络中或置于 VPN 之后
• 将已发布端口保留在 loopback 上（docker-compose.http.yml 绑定 127.0.0.1:8765），这样只有同一主机上的反向代理才能访问
• 使用反向代理强制执行 IP 允许列表
• 在反向代理层添加 Basic Auth / mTLS / OAuth2 代理
• 使用专用的低权限 DSM 用户（前文安全警告中已有建议）

🌟 Xiaozhi 集成

全新的统一架构支持两个客户端同时运行！

工作原理

• ENABLE_XIAOZHI=false（默认）：通过 stdio 为 Claude/Cursor 提供标准 MCP 服务
• ENABLE_XIAOZHI=true：支持多客户端的桥接服务，可同时支持：
  • 📡 Xiaozhi：WebSocket 连接
  • 💻 Claude/Cursor：stdio 连接

设置步骤

1. 添加到你的 .env 文件：

ENABLE_XIAOZHI=true
XIAOZHI_TOKEN=your_xiaozhi_token_here

2. 正常运行：

# Same command, different behavior based on environment
python main.py
# OR
docker-compose up

主要功能

• ✅ 零配置冲突：一个服务支持多个客户端
• ✅ 并行运行：两个客户端可以同时工作
• ✅ 提供所有工具：Xiaozhi 可使用所有 Synology MCP 工具
• ✅ 向后兼容：现有配置无需更改即可运行
• ✅ 自动重新连接：处理 WebSocket 连接中断
• ✅ 通过环境变量控制：使用简单的布尔标志即可启用/禁用

启动消息

仅 Claude/Cursor 模式：

🚀 Synology MCP Server
==============================
📌 Claude/Cursor only mode (ENABLE_XIAOZHI=false)

双客户端模式：

🚀 Synology MCP Server with Xiaozhi Bridge
==================================================
🌟 Supports BOTH Xiaozhi and Claude/Cursor simultaneously!

🛠️ 可用的 MCP 工具

🔐 身份验证

• synology_status - 检查身份验证状态和活动会话
• synology_list_nas - 从 settings.json 列出所有已配置的 NAS
• synology_login - 使用 Synology NAS 进行身份验证 （有条件提供）
• synology_logout - 注销会话 （有条件提供）

📁 文件系统操作

• list_shares - 列出所有可用的 NAS 共享
• list_directory - 列出目录内容及元数据
  • path（必填）：以 / 开头的目录路径
• get_file_info - 获取文件或目录的详细信息
  • path（必填）：以 / 开头的文件路径
• get_file_content - 读取严格 UTF-8 文本或无损 Base64 内容
  • path（必填）：以 / 开头的文件路径
  • encoding（可选）：text（默认）或 base64
  • max_bytes（可选）：读取的最大原始字节数（默认为 1 MiB，硬性上限为 8 MiB）
• search_files - 按名称递归搜索文件和文件夹
  • path（必填）：搜索目录
  • pattern（必填）：名称中不区分大小写的子字符串（例如：invoice、.pdf）。通配符没有特殊作用——DSM 对 report 和 *report* 的匹配结果相同。
• create_file - 创建包含内容的新文件
  • path（必填）：以 / 开头的完整文件路径
  • content（可选）：文件内容（默认为空字符串）
  • overwrite（可选）：是否覆盖现有文件（默认：false）
  • encoding（可选）：text（默认）或严格的 base64；解码后的内容上限为 8 MiB
• create_directory - 创建新目录
  • folder_path（必填）：以 / 开头的父目录路径
  • name（必填）：新目录名称
  • force_parent（可选）：如有需要则创建父目录（默认：false）
• delete - 删除文件或目录（自动检测类型）
  • path（必填）：以 / 开头的文件或目录路径
• rename_file - 重命名文件或目录
  • path（必填）：当前文件路径
  • new_name（必填）：新文件名
• move_file - 将文件移动到新位置
  • source_path（必填）：源文件路径
  • destination_path（必填）：目标路径
  • overwrite（可选）：覆盖现有文件
• copy_file - 在 NAS 内复制普通文件，无需通过 MCP 客户端传输文件字节
  • source_path（必填）：源文件路径
  • destination_folder（必填）：现有目标目录；保留文件名

copy_file 会验证目标路径和字节数。对于正在使用的 SQLite 数据库，它并不是可靠一致的备份方式；如果数据库在复制期间可能发生变化，请使用 SQLite 的在线备份机制。

📥 下载站管理

• ds_get_info - 获取下载站信息
• ds_list_tasks - 列出所有下载任务及其状态
  • offset（可选）：分页偏移量
  • limit（可选）：返回的任务数上限
• ds_create_task - 创建新的下载任务
  • uri（必填）：下载 URL 或磁力链接
  • destination（可选）：下载文件夹路径
• ds_pause_tasks - 暂停下载任务
  • task_ids（必填）：任务 ID 数组
• ds_resume_tasks - 恢复已暂停的任务
  • task_ids（必填）：任务 ID 数组
• ds_delete_tasks - 删除下载任务
  • task_ids（必填）：任务 ID 数组
  • force_complete（可选）：强制删除已完成的任务
• ds_get_statistics - 获取下载/上传统计信息

🏥 健康监控

• synology_system_info - 获取系统型号、序列号、DSM 版本、运行时间和温度
• synology_utilization - 获取 CPU、内存、交换空间和磁盘 I/O 的实时利用率
• synology_disk_health - 列出所有物理磁盘及其 SMART 状态、型号、温度和容量
• synology_disk_smart - 获取指定磁盘的详细 SMART 属性
• synology_volume_status - 列出所有卷及其状态、容量、使用情况和文件系统类型
• synology_storage_pool - 列出 RAID／存储池及其级别、状态和成员磁盘
• synology_lun_list - 列出所有 iSCSI LUN 及其名称、UUID、容量、类型、状态和所在卷。要查看 LUN 连接到哪个目标，请使用 synology_target_list——DSM 不会从 LUN 端报告映射关系。
• synology_lun_get - 获取单个 iSCSI LUN 的详细信息
  • name（必填）：来自 synology_lun_list 输出的 LUN 名称或 UUID
• synology_network - 获取网络接口状态和传输速率

SAN Manager（iSCSI 配置）

封装 SYNO.Core.ISCSI.LUN 和 SYNO.Core.ISCSI.Target。已在 RS1221+ 上的 DSM 7.3.2-86009 Update 4 中验证；其他 DSM 版本可能有所不同。对于 DSM 自身的拒绝， 会按原样报告，而不会擅自判断。

• synology_lun_create - 在卷上创建 LUN；返回其 uuid 和 lun_id
  • 必填：name、location（例如 /volume2）、size（单位为字节）
  • type（可选）：thin（默认值，DSM BLUN）、advanced、file，或 DSM 原始类型名称。请注意，thin 和 THIN 并不相同：小写形式是 BLUN 的友好别名，大写形式则是 DSM 中不同的旧类型。在本工具测试所用的 btrfs 卷上，厚置备类型遭到拒绝。
  • description（可选）
• synology_lun_delete - **破坏性操作。**删除 LUN 及其上的所有内容
  • 必填：uuid 和 confirm: true
• synology_target_list - 列出目标及其 IQN、身份验证类型和映射到各目标的 LUN
• synology_target_get - 通过 target_id 获取单个目标
• synology_target_create - 创建目标；返回其 target_id
  • name 为必填项；iqn 默认值为 iqn.2000-01.com.synology:<name>
  • chap_user + chap_password 可启用 CHAP。必须同时提供两者，或都不提供——只提供一个或提供空字符串都会遭到拒绝，而不会悄悄创建不启用身份验证的目标。两者都不提供时，任何能够连接到该目标的发起端都可访问它。
  • max_sessions（可选，0 = DSM 默认值）
• synology_target_map_lun - 将 LUN 映射到目标（target_id、lun_uuids）
• synology_target_unmap_lun - **破坏性操作。**取消 LUN 映射，并断开正在使用这些 LUN 的发起端（target_id、lun_uuids、confirm: true）

这些工具会拒绝任何未声明的参数，而不是将其忽略：如果 chap_user 拼写错误，原本可能会创建未启用身份验证的目标；如果 type 拼写错误，则会悄悄采用默认值。

• synology_ups - 获取 UPS 状态、电池电量和电源读数
• synology_services - 列出已安装的软件包及其运行状态
• synology_system_log - 获取近期系统日志条目
• synology_health_summary - 汇总系统信息、利用率、磁盘健康状况和卷状态

🐳 容器管理器

• synology_container_list - 列出容器管理器容器
  • offset（可选）：分页偏移量
  • limit（可选）：返回的容器数量上限
  • container_type（可选）：容器筛选条件（默认值：all）
• synology_container_health_summary - 汇总容器状态、健康状况、重启次数和镜像
• synology_container_disk_usage - 显示通过容器管理器 API 提供的只读磁盘使用情况摘要
• synology_container_get - 获取容器管理器容器
  • name（必填）：容器名称
• synology_container_start - 启动容器管理器容器
  • name（必填）：容器名称
• synology_container_stop - 停止容器管理器容器
  • name（必填）：容器名称
• synology_container_restart - 重启容器管理器容器
  • name（必填）：容器名称
• synology_container_delete - 删除容器管理器容器
  • name（必填）：容器名称
  • force（可选）：强制删除（默认值：false）
  • preserve_profile（可选）：保留 Synology 容器配置文件（默认值：true）
• synology_container_logs - 获取容器管理器容器日志
  • name（必填）：容器名称
  • since（可选）：日志起始时间／筛选条件
  • offset（可选）：分页偏移量（默认值：0）
  • limit（可选）：返回的日志行数上限（默认值：1000）
• synology_container_resource - 获取容器管理器容器的实时资源使用情况
  • name（必填）：容器名称
• synology_container_project_list - 列出容器管理器项目
• synology_container_project_get - 获取容器管理器项目（省略 Compose、环境变量和密钥字段）
  • name（必填）：项目名称
• synology_container_project_create - 创建并保存容器管理器项目定义
  • name（必填）：项目名称
  • share_path（必填）：NAS 上的项目文件夹路径
  • content（必填）：Docker Compose YAML 内容
  • enable_service_portal（可选）：启用 Synology 服务门户（默认值：false）
  • service_portal_name（可选）：服务门户名称
  • service_portal_port（可选）：服务门户端口
  • service_portal_protocol（可选）：服务门户协议（默认值：http）
  • 保存 Compose 定义；调用 synology_container_project_build 以生成项目。
• synology_container_project_update - 更新容器管理器项目
  • name（必填）：项目名称
  • content（必填）：Docker Compose YAML 内容
  • enable_service_portal（可选）：启用 Synology 服务门户
  • service_portal_name（可选）：服务门户名称
  • service_portal_port（可选）：服务门户端口
  • service_portal_protocol（可选）：服务门户协议
• synology_container_project_start - 启动容器管理器项目
  • name（必填）：项目名称
• synology_container_project_stop - 停止容器管理器项目
  • name（必填）：项目名称
• synology_container_project_restart - 重启容器管理器项目
  • name（必填）：项目名称
• synology_container_project_build - 生成或重建已保存的容器管理器项目
  • name（必填）：项目名称
• synology_container_project_clean - 清理容器管理器项目
  • name（必填）：项目名称
• synology_container_project_delete - 删除容器管理器项目
  • name（必填）：项目名称
• synology_container_image_list - 列出容器管理器镜像
  • offset（可选）：分页偏移量
  • limit（可选）：返回的镜像数量上限
  • show_dsm（可选）：包含 DSM 镜像（默认值：false）
• synology_container_image_get - 获取容器管理器镜像
  • name（必填）：镜像仓库名称
  • tag（可选）：镜像标签（默认值：latest）
• synology_container_image_delete - 删除容器管理器镜像
  • name（必填）：镜像仓库名称
  • tag（可选）：镜像标签（默认值：latest）
• synology_container_image_prune - 移除任何容器都未使用的镜像
  • synology_container_image_prune_preview 会在清理前提供只读候选列表
  • 仅使用容器管理器 API 删除可安全识别的未使用带标签镜像，并报告无法通过 DSM 移除的悬空镜像
  • 不会移除容器、网络或构建缓存
• synology_container_image_pull - 拉取容器管理器镜像
  • repository（必填）：镜像仓库名称
  • tag（可选）：镜像标签（默认值：latest）
• synology_container_registry_list - 列出容器管理器注册表
• synology_container_registry_search - 搜索容器管理器注册表
  • query（必填）：镜像搜索查询
  • offset（可选）：分页偏移量
  • limit（可选）：返回结果数量上限
• synology_container_registry_tags - 列出注册表镜像的标签
  • repository（必填）：镜像仓库名称
  • offset（可选）：分页偏移量
  • limit（可选）：返回的标签数量上限
• synology_container_registry_download - 下载注册表镜像
  • repository（必填）：镜像仓库名称
  • tag（可选）：镜像标签（默认值：latest）
• synology_container_network_list - 列出容器管理器网络
• synology_container_network_get - 获取容器管理器网络
  • name（必填）：网络名称
• synology_container_network_create - 创建容器管理器网络
  • name（必填）：网络名称
  • driver（可选）：网络驱动程序（默认值：bridge）
  • subnet（可选）：子网 CIDR
  • gateway（可选）：网关 IP
  • ip_range（可选）：可分配 IP 范围 CIDR
  • enable_ipv6（可选）：启用 IPv6（默认值：false）
• synology_container_network_delete - 删除容器管理器网络
  • name（必填）：网络名称

📦 NFS 管理

• synology_nfs_status - 获取 NFS 服务状态和配置
• synology_nfs_enable - 启用或禁用 NFS 服务
• synology_nfs_list_shares - 列出所有共享文件夹及其 NFS 权限
• synology_nfs_set_permission - 设置共享文件夹的 NFS 客户端访问权限

🔀 登录门户反向代理

• synology_reverse_proxy_list - 列出反向代理条目（控制面板 → 登录门户 → 高级 → 反向代理），包括源、目标、HSTS、WebSocket、自定义标头和访问控制配置文件
• synology_reverse_proxy_get - 按 UUID 或描述获取单个条目
• synology_access_control_profile_list - 列出条目可引用的访问控制配置文件
• synology_reverse_proxy_create - 创建条目；如果描述已被使用，则拒绝创建
• synology_reverse_proxy_update - 修改条目的部分字段，保留其余字段
• synology_reverse_proxy_delete - 有破坏性。 删除条目 （需要 confirm=true）
• 每次写入都会使 DSM 重建并重新加载其 nginx 配置，在小型 NAS 型号上可能需要一分钟。写入操作超时后会报告 outcome_unknown: true — 重试前请先列出条目。

🧠 Claude Code / Claude.ai 技能

对于 Claude Code、Claude Desktop 和 claude.ai 用户，本仓库提供了 Anthropic Agent Skill，指导 Claude 高效使用 MCP 工具 — 选择合适的工具、在多 NAS 设置中指定正确的 NAS、优先使用聚合健康检查而非分散调用，以及采用正确的路径约定。

该技能位于 skills/synology-nas/，通过七个领域（身份验证、文件、下载、健康、容器、共享/NFS、用户管理）逐步披露信息。

安装：

• Claude Code：将文件夹复制或符号链接到 ~/.claude/skills/synology-nas/
• Claude.ai / Claude Desktop：通过 Skills 设置页面上传 synology-nas/ 文件夹

该技能仅作补充 — 可与 MCP 配合使用，且只会在提示词与 Synology/NAS 相关时触发。

⚙️ 配置选项

⚠️ 安全警告：使用专用账户

对于此 MCP 服务，请创建具有适当权限的专用 Synology 用户账户。该账户应：

• 仅具有最低限度的必要权限（不要使用管理员账户！）
• 专门用于 MCP 服务自动化
• 现已支持 2FA — 如果你的 DSM 账户已启用 2FA，请参阅下方的 2FA / OTP 账户部分，以提供 otp_code（一次性）或 device_id（持久）字段。过去要求“不得启用 2FA”的说明 现已不再适用。

使用 settings.json（推荐）

变量	必需	默认值	描述
SYNOLOGY_URL	是*	-	NAS 基础 URL（例如，http://192.168.1.100:5000）
SYNOLOGY_USERNAME	是*	-	用于身份验证的用户名
SYNOLOGY_PASSWORD	是*	-	用于身份验证的密码
AUTO_LOGIN	否	true	服务启动时自动登录
VERIFY_SSL	否	false	验证 SSL 证书
DEBUG	否	false	启用调试日志记录
ENABLE_XIAOZHI	否	false	启用 Xiaozhi WebSocket 桥接
XIAOZHI_TOKEN	仅 Xiaozhi	-	Xiaozhi 的身份验证令牌
XIAOZHI_MCP_ENDPOINT	否	wss://api.xiaozhi.me/mcp/	Xiaozhi WebSocket 端点

*自动登录和默认操作必需

使用 settings.json（多 NAS 支持）

要管理多台 Synology NAS 设备，请使用 XDG 标准配置目录（~/.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!

注意： 这遵循 XDG 基本目录规范——~/.config/ 是 Linux/macOS 上存放用户配置文件的标准位置。你可以通过设置 XDG_CONFIG_HOME 环境变量来自定义位置。

使用 Docker： docker-compose.yml 会自动将你的 ~/.config/synology-mcp 目录挂载到容器中的 /home/mcpuser/.config/synology-mcp，因此多 NAS 支持开箱即用，也适用于 Docker。

settings.json 格式：

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

配置字段：

字段	必填	说明
host	是*	NAS 主机名或 IP 地址
port	否	API 端口（默认值：HTTP 为 5000，HTTPS 为 5001）
url	是*	完整的基础 URL（例如：https://nas.example.com）；优先于 host/port——用于位于反向代理之后的 NAS
username	是	NAS 用户名
password	是	NAS 密码
otp_code	否	一次性 6 位双重身份验证代码（仅首次登录时使用，之后请移除）
device_id	否	DSM 提供的长期有效可信设备令牌（did）；以后登录时可跳过 OTP
note	否	可选备注，供你参考

*每个 NAS 条目都必须提供 host 或 url。

注意：

• 如果端口为 5001，服务器将使用端口 5001（HTTPS）；否则默认使用 HTTP（5000）
• host/port 格式始终会附加端口，并根据端口推导协议，因此无法表示默认使用 443 端口的 https://nas.example.com；对于反向代理设置，请直接设置 url
• 文件权限：出于安全考虑，必须执行 chmod 600 ~/.config/synology-mcp/settings.json
• 如果权限过于宽松，服务器将拒绝加载设置
• .env 和 settings.json 可以同时使用（settings.json 优先）

⚠️ 安全建议

settings.json 文件权限：

• Linux/macOS（POSIX）： 必须执行 chmod 600 ~/.config/synology-mcp/settings.json。如果文件可被组用户或其他用户读取/写入，或文件归其他用户所有，服务器将拒绝加载。
• Windows： 通过 NTFS ACL 强制实施访问控制，而非 POSIX 模式位。服务器会审查文件的安全描述符，并且只有满足以下全部三项条件才会加载：(1) 所有者 SID 与当前用户匹配；(2) DACL 存在（会拒绝 NULL DACL——即“所有人完全访问”）；(3) 没有任何允许 ACE 向允许列表以外的主体授予访问权限：当前用户、NT AUTHORITY\SYSTEM 和 BUILTIN\Administrators。任何继承的 Everyone / BUILTIN\Users / Authenticated Users 授权都会导致检查失败。

  • 需要可选的 pywin32 包：pip install pywin32。如果未安装 pywin32，服务器会默认拒绝，并拒绝加载 settings.json。 接受未经验证文件的风险的运维人员可以设置 SYNOLOGY_MCP_ALLOW_UNVERIFIED_WINDOWS_ACL=true 以重新启用加载。

  • 服务器通过 XDG_CONFIG_HOME 解析文件位置（默认为 Path.home() / ".config"），因此在 Windows 上，文件位于 %USERPROFILE%\.config\synology-mcp\settings.json，除非设置了 XDG_CONFIG_HOME。

  • 在提升权限的 PowerShell 提示符中锁定文件（使用与服务器加载时相同的路径）：

    # 按照服务器相同的方式解析路径：如果已设置则使用 $XDG_CONFIG_HOME，
    # 否则使用 %USERPROFILE%\.config。此处会遵循上文所述的覆盖设置。
    $cfg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$env:USERPROFILE\.config" }
    $f = "$cfg\synology-mcp\settings.json"
    # 服务器的 ACL 审计要求：所有者 == 当前用户、DACL 不为 NULL，且
    # 不存在 {当前用户、SYSTEM、Administrators} 之外的允许 ACE。以下步骤
    # 可满足这三项要求。
    #
    # 对所有内置主体使用 *<SID> 格式：诸如
    # "Administrators" / "Everyone" / "Users" 这样的账户名会在非英语版 Windows
    # 上本地化（例如德语中的 "Administratoren"），因此无法解析。以下 SID
    # 不受区域设置影响：
    #   *S-1-1-0            Everyone
    #   *S-1-5-11           Authenticated Users
    #   *S-1-5-32-545       BUILTIN\Users
    #   *S-1-5-32-544       BUILTIN\Administrators
    #
    # 1. 确保文件归当前用户所有（审计会拒绝其他所有者）。/setowner 需要提升权限。
    icacls $f /setowner "${env:USERNAME}"
    # 2. 删除继承的 ACE，然后撤销常见的外部授权。/grant:r
    #    只会替换指定主体的权限，因此要先撤销。
    icacls $f /inheritance:r
    icacls $f /remove:g "*S-1-1-0" "*S-1-5-11" "*S-1-5-32-545"
    # 在此处重新运行 `icacls $f`；如果仍显示你自己的用户或
    # Administrators 之外的主体，请运行：icacls $f /remove:g "<that principal>"
    # 3. 授予当前用户和 Administrators 完全控制权限。
    icacls $f /grant:r "${env:USERNAME}:(F)"
    icacls $f /grant:r "*S-1-5-32-544:(F)"   # BUILTIN\Administrators（不受区域设置影响）
    

    如果文件是全新的，/remove:g 步骤不会产生影响。

  • 验证：icacls "$f" — 应只显示你的用户和 *S-1-5-32-544（Administrators）。

SSL 证书验证（VERIFY_SSL）：

• 默认值为 false，以支持内部 NAS 设备上的自签名证书
• 如果你的 NAS 有有效的 SSL 证书（例如来自 Let's Encrypt 或企业 CA），请设置 VERIFY_SSL=true
• 设置 VERIFY_SSL=false 会禁用证书验证，使你的连接容易受到中间人（MITM）攻击
• 切勿在不受信任的网络上禁用 SSL 验证

自动登录（AUTO_LOGIN）：

• 默认值为 true，方便使用 settings.json
• 凭据会以 0600 权限安全地存储在 ~/.config/synology-mcp/settings.json 中
• 如果你更倾向于手动登录，请设置 AUTO_LOGIN=false 并使用 synology_login 工具

双重身份验证 / OTP 账户（可选）：

MCP 服务支持启用了双重身份验证的 DSM 账户。有两种使用方式：

1. 通过 synology_login 工具一次性使用 OTP（交互式）：

   { "base_url": "https://nas.lan:5001", "username": "alice", "password": "…", "otp_code": "123456" }
   

   DSM 会在响应中返回一个 did（设备令牌）— 将该值复制到 settings.json（如下），即可在之后重启进程时跳过 OTP。

2. 持久化的受信任设备令牌（建议用于 AUTO_LOGIN=true）：

   在 settings.json 中为每台 NAS 添加 otp_code（一次性，仅首次登录使用）和／或 device_id（长期有效，持续使用）字段：

   {
     "synology": {
       "nas1": {
         "host": "192.168.1.100", "port": 5001,
         "username": "alice", "password": "…",
         "otp_code": "123456",
         "note": "primary — 2FA enabled"
       }
     }
   }
   

   工作流：

   1. 将 otp_code 设置为身份验证器生成的最新 6 位代码，然后启动服务。
   2. 首次成功登录后，服务会记录一条类似以下内容的警告： nas1: 2FA bootstrap — copy this device_id into settings.json to skip OTP on future starts: <did> 复制 <did> 的值。
   3. 将其粘贴到 device_id 中，并删除 otp_code。
   4. 从现在起，DSM 会将此进程视为受信任设备 — 重启、DSM 错误 119 后重新登录，以及容器管理器会话均可跳过 OTP。

   如果存在 device_id，它的优先级高于 otp_code（受信任设备路径）。使用旧版 .env 的用户可以设置一次性的 SYNOLOGY_OTP_CODE 环境变量；要使用持久化的 device_id，请迁移到 settings.json（较长的不透明令牌不适合直接放入环境变量）。

📖 使用示例

📁 文件操作

✅ 创建文件和目录

// 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 同时支持 stdio 和 WebSocket 客户端
• ✅ 环境变量控制 - 通过 ENABLE_XIAOZHI 环境变量切换模式
• ✅ 多客户端支持 - 同时支持 Claude/Cursor 和 Xiaozhi 访问
• ✅ 安全身份验证 - 使用 RSA 加密传输密码
• ✅ 会话管理 - 在多个 NAS 设备间保持会话
• ✅ 完整文件操作 - 创建、删除、列出、搜索、重命名和移动文件，并提供详细元数据
• ✅ 目录管理 - 执行递归目录操作，并进行安全检查
• ✅ 下载站 - 完整的种子和下载管理
• ✅ Docker 支持 - 轻松进行容器化部署
• ✅ 向后兼容 - 现有配置无需更改即可使用
• ✅ 错误处理 - 提供全面的错误报告和恢复机制

🏗️ 架构

文件结构

mcp-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
├── pyproject.toml            # Dependencies (single source of truth)
└── .env                      # Configuration

模式选择

• ENABLE_XIAOZHI=false → main.py → mcp_server.py（仅 stdio）
• ENABLE_XIAOZHI=true → main.py → multiclient_bridge.py → mcp_server.py（支持两个客户端）

适用于各种工作流，从简单的 Claude/Cursor 使用场景到高级多客户端设置！ 🚀