synology-filestation-mcp

基于 Synology File Station Web API 封装的 MCP (Model Context Protocol) 服务，让 AI Agent 可以直接管理群晖 NAS 上的文件：浏览目录、搜索、上传下载、创建/重命名/复制/移动/删除、压缩/解压等。

支持两种运行模式：

• stdio 本地模式（src/index.js）：在个人电脑上跑，凭据放本地环境变量
• Streamable HTTP 远程模式（src/http.js）：集中部署到服务器，多人共用，各自的 NAS 凭据通过请求头传入

环境要求

• Node.js >= 18（开发使用 Node 24 验证；低版本 glibc 服务器可用 unofficial-builds 的 glibc-217 构建）
• DSM 7.x（已在 DSM 7.2 上实测通过）

安装

npm install

模式一：stdio 本地模式

通过环境变量提供 NAS 连接信息（也可复制 .env.example 为 .env 填写，服务启动时自动加载）：

变量	说明
SYNOLOGY_HOST	DSM 地址，如 http://192.168.1.1:5000（不带末尾斜杠）
SYNOLOGY_USER	DSM 账号
SYNOLOGY_PASSWORD	DSM 密码
SYNOLOGY_DOWNLOAD_DIR	可选，fs_download 默认本地保存目录

以 Claude Desktop 为例，配置 claude_desktop_config.json：

{
  "mcpServers": {
    "synology-filestation": {
      "command": "node",
      "args": ["D:/path/to/synology-filestation-mcp/src/index.js"],
      "env": {
        "SYNOLOGY_HOST": "http://192.168.1.1:5000",
        "SYNOLOGY_USER": "your_username",
        "SYNOLOGY_PASSWORD": "your_password"
      }
    }
  }
}

模式二：HTTP 远程模式（多人共用）

服务端启动：

# .env 或环境变量
SYNOLOGY_HOST=http://192.168.1.1:5000   # 默认 NAS 地址（客户端可用 X-NAS-Host 覆盖）
PORT=3000
MCP_AUTH_TOKEN=<随机令牌>                # 设置后客户端必须带 Bearer token

npm run start:http

特性：

• 多用户：每个 MCP 会话独立持有 NAS 登录态（sid 池），互不串号
• 凭据传递：客户端通过请求头提供自己的 NAS 账号 X-NAS-User / X-NAS-Password，可选 X-NAS-Host 覆盖服务端默认；缺省回落到服务端环境变量（支持服务端统一托管账号）
• 鉴权：设置 MCP_AUTH_TOKEN 后，所有 /mcp 请求必须带 Authorization: Bearer <token>
• 会话管理：空闲 30 分钟自动清理并登出 NAS（SESSION_IDLE_TTL_MS 可调）
• 健康检查：GET /health

客户端配置（支持远程 MCP 的客户端，url 方式）：

{
  "mcpServers": {
    "synology-filestation": {
      "url": "http://<部署服务器>:3000/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_AUTH_TOKEN>",
        "X-NAS-User": "同事自己的 NAS 账号",
        "X-NAS-Password": "同事自己的 NAS 密码"
      }
    }
  }
}

systemd 部署示例：

[Unit]
Description=Synology FileStation MCP (HTTP)
After=network.target

[Service]
WorkingDirectory=/opt/synology-filestation-mcp
ExecStart=/usr/bin/node src/http.js
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

安全提示：生产环境建议用 HTTPS（反向代理）终止 TLS，避免 NAS 凭据在请求头中明文传输。

工具清单

工具	说明	底层 API
fs_list_shares	列出共享文件夹	SYNO.FileStation.List / list_share
fs_list	列出目录内容（支持分页、排序、通配符过滤）	SYNO.FileStation.List / list
fs_get_info	获取文件/目录详细信息	SYNO.FileStation.List / getinfo
fs_search	按模式搜索文件（自动轮询直到完成）	SYNO.FileStation.Search / start+list
fs_search_stop	停止搜索任务	SYNO.FileStation.Search / stop
fs_search_clean	清理所有搜索任务	SYNO.FileStation.Search / clean
fs_create_folder	创建文件夹	SYNO.FileStation.CreateFolder / create
fs_rename	重命名文件/文件夹	SYNO.FileStation.Rename / rename
fs_copy_move	复制/移动（异步任务，返回 taskid）	SYNO.FileStation.CopyMove / start
fs_task_status	查询后台任务进度	SYNO.FileStation.BackgroundTask / list
fs_delete	删除（异步任务，不可恢复）	SYNO.FileStation.Delete / start
fs_download	下载 NAS 文件到本机目录	SYNO.FileStation.Download / download
fs_upload	上传本机文件到 NAS	SYNO.FileStation.Upload / upload
fs_compress	NAS 端压缩为 zip/7z（异步任务）	SYNO.FileStation.Compress / start
fs_extract	NAS 端解压缩（异步任务，目标目录需已存在）	SYNO.FileStation.Extract / start

测试

SYNOLOGY_HOST=http://192.168.0.196:5000 SYNOLOGY_USER=xxx SYNOLOGY_PASSWORD=xxx npm test

冒烟测试会对 NAS 执行完整链路：登录 → 列出共享文件夹 → 建目录 → 上传 → 列表 → 查信息 → 重命名 → 复制 → 搜索 → 下载校验内容 → 删除清理 → 登出。测试会在某个可写共享文件夹下创建 mcp-smoke-test 临时目录，结束后自动删除。

另有扩展能力测试 test/extended.mjs（node test/extended.mjs，同样读取环境变量）：覆盖 23 种文件格式（文档/图片/视频/音频/压缩包/数据库/虚拟机镜像）的上传下载逐字节校验、批量复制/移动/删除、NAS 端解压、回收站落点检查，以及权限与安全能力边界探测。

实现说明（DSM 7.x 兼容性）

• 启动时先调 SYNO.API.Info 发现各 API 的 path 与版本，登录走 SYNO.API.Auth（format=sid）。
• SYNO.FileStation.List v2 的 additional 参数要求 JSON 数组格式（如 ["size","time"]），逗号分隔字符串会被静默忽略。
• 文件信息查询使用 SYNO.FileStation.List / getinfo（SYNO.FileStation.Info / get 返回的是 File Station 服务器配置，不是文件信息）。
• 上传使用 API version 2：实测 v3 下 overwrite 参数不生效，同名文件返回 414。上传时 sid 通过表单字段和 Cookie: id=<sid> 双通道传递。
• 复制/移动/删除为异步任务；DSM 7.x 的 SYNO.FileStation.BackgroundTask 只有 list 方法（无 status），按 taskid 过滤查询进度。
• 搜索为异步任务，工具内部轮询 list 直至 finished。
• SYNO.FileStation.Extract 的目标目录必须预先存在，否则返回 408（No such file or directory）。
• SYNO.FileStation.Compress 依赖账号在 DSM 中的应用权限；若返回 105（session does not have permission），需在 DSM 控制面板为账号授予相应权限。

能力边界（不属于 File Station API 范围）

以下能力在官方 File Station API 中不存在，本 MCP 无法提供：

• ACL 权限管理：属 DSM 控制面板功能（SYNO.Core.* 私有接口，非公开 File Station API）。
• 共享文件夹 AES 加密：属 DSM 存储管理功能（创建/挂载加密共享文件夹）。
• 防篡改（只读/不可删除标记）：File Station API 无设置入口；可通过共享文件夹只读挂载间接实现。
• 网络回收站：删除行为自动遵循各共享文件夹的回收站设置（开启后删除的文件进入 <share>/#recycle），API 无需也无法单独控制。

目录结构

src/
  index.js    stdio 入口（本地模式）
  http.js     HTTP 入口（远程模式，Streamable HTTP + 多用户会话池）
  server.js   共享的 MCP Server 构建（注册全部工具）
  env.js      .env 加载
  client.js   Synology API 客户端：API 发现、认证、请求封装、错误码映射
  tools/      每个 File Station API 一个工具模块
test/
  smoke.mjs      对真实 NAS 的全链路冒烟测试（stdio 层逻辑）
  http-smoke.mjs HTTP 模式自测（鉴权、会话、工具调用、会话关闭）
  extended.mjs   扩展能力测试（多格式、批量、解压、回收站）