Synology NAS

mcp-synology

适用于 Synology NAS 设备的 MCP 服务。它将 Synology DSM API 功能作为 MCP 工具提供，供 Claude 使用。

已针对 DSM 7.1、7.2.2、7.3.2 和 7.4.1 进行测试：CI 会在每个版本的虚拟 DSM 上运行所有模块的集成测试。候选发布版本也会在真实 NAS（DSM 7.1.1）上进行实时测试，由 AI 客户端驱动这些工具：0.10.0 版本由 Claude Code、通过桌面应用运行的 claude.ai，以及远程机器上的 Agent，以管理员、普通、只读和受限用户身份进行测试。请参阅 docs/live-testing.md。

从 synology-mcp 迁移

如果你要从 synology-mcp（v0.3.x 或更早版本）升级，该软件包已重命名。迁移脚本会自动处理配置、状态、密钥环条目和 Claude Desktop 配置：

# Download and run the migration script
curl -O https://raw.githubusercontent.com/cmeans/mcp-synology/main/scripts/migrate-from-synology-mcp.py
python migrate-from-synology-mcp.py          # dry run — preview changes
python migrate-from-synology-mcp.py --apply  # apply changes

脚本会迁移：

• 配置目录（~/.config/synology-mcp/ → ~/.config/mcp-synology/）
• 状态目录（~/.local/state/synology-mcp/ → ~/.local/state/mcp-synology/）
• 密钥环凭据
• Claude Desktop 的 claude_desktop_config.json（更新命令和路径）

有关破坏性变更的完整详情，请参阅 CHANGELOG.md。

支持的模块

File Station

浏览、搜索、传输和管理 NAS 上的文件。共提供 15 个工具，分为两个权限级别：

• READ — list_shares、list_files、list_recycle_bin、search_files、get_file_info、get_dir_size、download_file
• WRITE — create_folder、rename、copy_files、move_files、delete_files、restore_from_recycle_bin、upload_file、file_task

对文件夹使用 download_file 时，会将 DSM 创建的 ZIP 保存为 <folder>.zip（如果指定了 filename，则使用该名称）。无法通过此方式下载整个共享文件夹（DSM 不会发送该文件夹），因此请求会被拒绝。

System

监控 NAS 健康状况和资源使用情况。提供 2 个只读工具：

• get_system_info — 获取 DSM 报告的所有信息。每个账户都能获取型号、序列号、DSM 版本、RAM、运行时间、NAS 本地时间和代码页，以及 NAS 配有传感器的部件温度。管理员账户还可获取 CPU、时区和当前 UTC 偏移量、NTP 服务、固件日期、DSM 的更新就绪和崩溃标志、eSATA 端口以及已连接的 USB、SATA 和 PCIe 设备；此外，在 DSM 7.2.2 及更高版本中，还可获取网卡标志，并在会报告冗余电源的型号上获取冗余电源信息。其他账户会收到一行说明哪些信息需要管理员权限
• get_resource_usage — 实时 CPU 负载、内存使用量、磁盘 I/O、网络吞吐量（需要管理员账户）

mcp-synology setup 只会写入 File Station 模块。要添加 System，请将它放在现有的 modules: 部分中（它没有写入工具，因此不需要 permission）：

modules:
  system:
    enabled: true

Download Station

管理 Download Station 队列和设置。共提供 12 个工具，分为两个权限级别：

• READ — list_downloads、get_download_info、get_download_stats、get_download_config、get_schedule
• WRITE — create_download、delete_download、pause_download、resume_download、edit_download、set_download_config、set_schedule

Download Station 为可选模块：mcp-synology setup 只配置 File Station。要启用它：

1. 从套件中心在 NAS 上安装 Download Station（如果尚未安装）。如果没有安装该软件包，工具仍会显示，但每次调用都会失败并返回 api_not_found。

2. 编辑配置文件。该文件为 ~/.config/mcp-synology/config.yaml；如果使用 Multi-NAS，则为 home-nas.yaml 之类的 NAS 专属文件。将 downloadstation 添加到现有的 modules: 部分中；不要再添加第二个 modules: 键。仅启用读取工具时使用 permission: read，启用全部 12 个工具时使用 permission: write：

   modules:
     filestation:          # already there
       enabled: true
       permission: write
     downloadstation:      # add this
       enabled: true
       permission: write   # or read
   

3. **检查配置：**运行 mcp-synology check --config <your config file>，即可报告 YAML 或验证错误，并确认登录仍然有效。

4. 重启 MCP 客户端（例如 Claude Desktop）。服务仅会在启动时读取配置。随后，Download Station 工具（list_downloads 等）就会与 File Station 工具一同显示。你可以让助手“列出我的下载”来试用。

如果账户不是管理员，请先阅读下方的 Accounts：非管理员账户需要执行一次性设置，才能运行 Download Station 任务。

**Accounts。**管理员（Download Station 管理员）可以使用所有工具。非管理员账户需要拥有 Download Station 应用权限（Control Panel → User & Group → [account] → Edit → Applications）。此外，工具还会强制执行或报告以下限制：

• 首次设置。 Download Station 在用户设置默认目标位置之前，不会启动非管理员用户的任务；这些任务会一直等待。尚未打开过 Download Station 的用户没有默认目标位置。使用 set_download_config(default_destination="<share>") 设置一次即可，DSM 只会为该用户应用此设置。在此之前，使用显式 destination 调用 create_download 仍会创建任务，但会警告任务不会启动。如果未指定 destination，则会拒绝请求并说明需要设置什么。只要没有可回退使用的默认目标位置，此拒绝规则就适用于任何账户，包括管理员。
• 仅限自己的任务。 list_downloads 和其他任务工具只能查看用户自己的任务。
• 设置。 get_download_config 显示的是用户自己的视图，而非 NAS 全局设置。set_download_config 只能更改用户自己的 default_destination；速度限制是 NAS 全局设置，因此会被拒绝，因为 DSM 会接受非管理员提交的设置，然后悄悄忽略。
• 计划。 get_schedule / set_schedule 中的每周计划和限速值需要管理员权限。非管理员仍可开启或关闭计划，此开关是 NAS 全局设置。

Torrent 文件。 使用 torrent_file_path 调用 create_download 会上传本地 .torrent 或 .nzb 文件，且文件只能来自允许的本地文件夹；默认情况下为你的 Downloads 文件夹。其他位置的文件都会在读取前被拒绝，包括指向其他类型文件的链接。要使用其他文件夹，请将其列入 allowed_local_paths，可以在配置的顶层（适用于每个模块），也可以在此模块的设置下。设置了顶层列表时，模块自己的列表会在其基础上添加路径。若未设置顶层列表，模块自己的列表会替换默认的 Downloads 文件夹，因此如果仍要使用它，请加入 ~/Downloads。

modules:
  downloadstation:
    enabled: true
    permission: write
    settings:
      allowed_local_paths:
        - ~/Downloads   # keep the default folder too
        - ~/Torrents

请参阅功能中的本地路径限制。Magnet 链接和 URL（uri）不受影响。

已知限制：

• destination 必须是现有文件夹：Download Station 不会创建缺失的文件夹。请先使用 File Station 的 create_folder 创建（/video/TV/New show；filestation 模块需要设置 enabled: true 和 permission: write），或在 DSM 自带的 File Station 中创建，然后以共享文件夹相对路径传入（video/TV/New show）。提示目标位置不存在的错误会说明此解决方法（#296）。
• 对于使用 username / password 的 URL，create_download 不会返回任务 ID。
• edit_download 只能更改目标位置。
• 无法选择 torrent 中的单个文件。
• 暂不支持 BT 搜索和 RSS 订阅源。
• delete_download(force_complete=true) 无法可靠地保留部分数据：DSM 仍会丢弃未完成的 HTTP 下载。DSM 也会拒绝对已完成任务执行此操作，工具会将其报告为未删除。

已针对 DSM 7.1（Download Station 3.9-4627）以及 DSM 7.2.2、7.3.2 和 7.4.1（Download Station 4.1-5012）进行测试。

Synology Photos

浏览、搜索、整理和分享 Synology Photos 图库，涵盖个人空间和共享空间。共提供 19 个工具，分为两个权限级别：

• READ — list_photos、list_photo_collections、get_photo、download_photos
• WRITE — upload_photos、photo_album、photo_share_link、photo_folder、copy_photos、move_photos、photo_task、tag_photos、edit_photo、edit_person、photo_request、merge_people、delete_photos、delete_photo_folders、delete_photo_albums

Photos 与 Download Station 一样，需要选择启用：从 Package Center 安装 Synology Photos，然后在现有的 modules: 部分中添加 photos，运行 mcp-synology check 检查配置，并重启 MCP 客户端。

modules:
  photos:
    enabled: true
    permission: write   # or read

账户。 账户需要拥有 Synology Photos 应用程序权限（控制面板 → 应用程序权限 → Synology Photos），个人空间则需要启用用户主目录服务（控制面板 → 用户与群组 → 高级 → 用户主目录）。必须在 Synology Photos 的设置中启用共享空间，并向该账户授予访问权限。缺少任何一项时，工具都会报告对应的名称。

须知：

• 编辑会更改原始文件。 Photos 会将评分、描述、标签、拍摄时间更改和旋转信息写入文件本身，因此文件的日期和大小会发生变化；备份和同步工具会将其视为新版本。
• 标签按名称指定。 只有在某个项目使用该标签时，标签才存在；从所有项目中移除该标签后，它就会被删除。
• 删除的文件 会移至所在空间所属共享文件夹的回收站（如果有）；Photos 本身没有回收站。大型复制、移动或删除操作会交由后台处理，并返回 photos:<id> 句柄，由 photo_task 跟进。
• 收藏和概念（Photos 识别出的事物和场景）需要 Synology Photos 1.9.1（DSM 7.2）；在 1.3.4 上使用时会以 not_supported 拒绝请求。
• 本地文件。 upload_photos 只会从允许的本地文件夹读取文件，download_photos 也只会将文件写入允许的本地文件夹（默认是你的 Downloads 文件夹）；allowed_local_paths 的说明请参阅上文 Download Station 种子文件相关说明。task_timeout（秒，默认值为 30，范围为 1 到 600；位于 photos: → settings: 下）用于设置复制、移动或删除操作在交由后台处理前的等待时长，也用于设置 upload_photos 停止启动新文件上传的时机（最多 45 秒，低于 Claude Desktop 约 60 秒的工具调用超时；它会列出尚未尝试的文件，供后续调用处理）。
• 暂不支持： 共享空间文件夹共享、People 中的人脸级编辑、访客向照片请求上传照片，以及更改 Photos 自身的设置。

已针对 DSM 7.1（Synology Photos 1.3.4）、DSM 7.2.2、7.3.2 和 7.4.1（Synology Photos 1.9.1）进行测试。有关各工具发送的内容以及相关的 DSM 行为，请参阅 docs/specs/photos-module-spec.md。

功能

• 交互式设置 — 通过引导式配置创建配置文件、存储凭据、处理 2FA，并生成 Claude Desktop 配置片段
• 权限级别 — 在工具注册时为每个模块强制设置 READ 或 WRITE。权限级别决定服务可以在 NAS 上执行哪些操作。在这台机器上写入文件的工具（download_file、download_photos）会标记为破坏性操作，以便客户端可以要求确认；除 create_folder、rename、upload_photos、create_download、pause_download 和 resume_download 之外的所有 WRITE 工具也会如此标记。只读连接会告知模型它限制了哪些工具，以及如何启用这些工具，这样模型就不会声称服务无法执行相应操作
• 长时间运行的操作会继续执行 — 大型删除、复制、移动或回收站还原操作会在调用等待期间报告进度；如果等待结束时操作仍在运行（默认 30 s），NAS 会继续处理：回复会提供一个 file_task 句柄，可用于检查任务状态、列出正在运行的操作或停止某个操作。请参阅File Station 设置。Photos 的 copy_photos、move_photos、delete_photos 和 delete_photo_folders 也会在 task_timeout（默认 30 s，最多 600 s）后交由后台处理，并提供一个 photos:<id> 句柄供 photo_task 使用
• 本地路径限制 — upload_file、download_file、upload_photos、download_photos 和 create_download 的种子文件只能使用 allowed_local_paths 中列出的本地文件夹；默认值为你的 Downloads 文件夹。可在配置文件顶层为所有模块设置，也可在各模块的设置中分别配置（File Station、Download Station 和 Photos 各自有独立列表）。设置顶层列表时，模块自己的列表会与其合并。若未设置顶层列表，则模块自己的列表会替换默认的 Downloads 文件夹，因此如果仍要使用该文件夹，请加入 ~/Downloads。create_download 只读取 .torrent 和 .nzb 文件。符号链接和 .. 会先解析，因此无法通过它们访问列表以外的路径。设置为 ["/"] 即可允许访问所有路径（macOS/Linux）
• 支持 2FA — 自动检测；通过设备令牌引导登录，并自动静默重新验证
• 安全存储凭据 — 集成 OS 钥匙串，在 macOS、Windows 和 Linux 上均可透明使用（包括从 Claude Desktop 使用）。请参阅 docs/credentials.md。
• 多 NAS 管理 — 使用独立的配置、凭据和状态管理多个 NAS 设备

快速开始

1. 运行设置

uvx mcp-synology setup

需要 uv。uvx 会自动下载并运行最新版本，无需单独安装。

设置过程会询问 NAS 主机、凭据和偏好设置。如果你的账户启用了 2FA，系统会提示你输入 OTP 验证码，并存储设备令牌，以便日后自动登录。

最后，系统会输出一段可直接复制粘贴的 Claude Desktop JSON 配置片段。

2. 添加到 Claude Desktop

将设置过程生成的配置片段复制到 claude_desktop_config.json，然后重启 Claude Desktop。配置内容大致如下：

{
  "mcpServers": {
    "synology-nas": {
      "command": "uvx",
      "args": ["mcp-synology", "serve", "--config", "~/.config/mcp-synology/nas.yaml"]
    }
  }
}

配置文件名（例如 nas.yaml）也可作为连接的自然标识符 — 你可以按 NAS 为文件命名（例如 home-nas.yaml、office-nas.yaml）。

在 Linux 上，服务会自动检测用于访问钥匙串的 D-Bus 会话套接字。如果自动检测失败，请在 Claude Desktop 配置中添加 "env": {"DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/<uid>/bus"}。设置命令会将此内容包含在生成的配置片段中。

3. 验证

uvx mcp-synology check                # Validates credentials work
uvx mcp-synology setup --list         # Shows all configured NAS instances

替代方案：全局安装

如果你更喜欢持久安装（可避免每次调用时都下载）。需要 uv — 可使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安装（macOS/Linux）；其他安装方式请参阅安装指南。

uv tool install mcp-synology
mcp-synology setup
mcp-synology check

替代方案：仅使用环境变量模式

如果设置了 SYNOLOGY_HOST，则无需配置文件。这适用于 Docker 或 CI 环境：

{
  "mcpServers": {
    "synology": {
      "command": "uvx",
      "args": ["mcp-synology", "serve"],
      "env": {
        "SYNOLOGY_HOST": "192.168.1.100",
        "SYNOLOGY_USERNAME": "your_user",
        "SYNOLOGY_PASSWORD": "your_password"
      }
    }
  }
}

或通过 CLI：

SYNOLOGY_HOST=192.168.1.100 uvx mcp-synology check

没有配置文件时，mcp-synology 始终以只读模式运行 File Station。没有环境变量可以启用其他模块或写入工具；如需使用这些功能，请使用配置文件（此时相同的变量会覆盖配置文件中的值）。变量如下：

变量	设置项	默认值
SYNOLOGY_HOST	connection.host（仅使用环境变量模式时必需）	—
SYNOLOGY_PORT	connection.port	5000，或使用 HTTPS 时为 5001
SYNOLOGY_HTTPS	connection.https（true、1 或 yes 表示开启；其他值均为关闭）	false
SYNOLOGY_USERNAME	auth.username	密钥环
SYNOLOGY_PASSWORD	auth.password	密钥环
SYNOLOGY_DEVICE_ID	auth.device_id（双重身份验证设备令牌）	密钥环
SYNOLOGY_INSTANCE_ID	instance_id（用于命名密钥环条目和状态文件夹）	根据主机推导
SYNOLOGY_LOG_LEVEL	logging.level（debug、info、warning、error）	info

双重身份验证支持

mcp-synology 完全支持启用了双重身份验证的 DSM 账户。系统会自动检测，无需特别配置：

1. 初始化 — mcp-synology setup 会检测双重身份验证，提示你输入 OTP 代码，并将设备令牌存储在密钥环中
2. 静默重新身份验证 — 后续登录会自动使用设备令牌（不会提示输入 OTP）
3. 按实例区分 — 每个 NAS 配置都有自己的设备令牌，因此混合使用启用和未启用双重身份验证的配置也没有问题

设备令牌没有固定的有效期：它会一直有效，直到在 DSM 中移除受信任设备（个人 > 安全性 > 登录活动），或 DSM 不再接受该令牌。如果 DSM 拒绝存储的令牌，错误消息会说明原因；请再次运行 mcp-synology setup，使用新的双重身份验证代码登录。

密钥环和凭据

凭据存储在操作系统的密钥环中，并可透明地访问：

平台	后端	说明
macOS	Keychain	开箱即用
Windows	Credential Manager	开箱即用
Linux	GNOME Keyring / KWallet	自动检测 D-Bus 会话，可在 Claude Desktop 中使用

凭据解析顺序：环境变量 > 配置文件 > 密钥环。显式来源优先于隐式默认值。

对于没有密钥环的环境（Docker、CI），请使用环境变量或在配置文件中内联填写凭据。

有关密钥环服务名称、多 NAS 配置以及如何检查或移除已存储凭据的信息，请参阅 docs/credentials.md。

更新

mcp-synology 会检查更新，并在 Claude Desktop 对话中通知你——如果 PyPI 上有较新版本，每个会话中的第一个工具响应都会包含通知。

如需通过 CLI 管理更新：

mcp-synology --check-update                 # Check for a newer version
mcp-synology --auto-upgrade enable           # Auto-upgrade on each interactive run
mcp-synology --revert                        # Roll back to previous version
mcp-synology --revert 0.1.0                  # Roll back to a specific version

如需禁用更新通知，请在配置文件的顶层添加：

# ~/.config/mcp-synology/config.yaml
check_for_updates: false

配置

交互式设置会为你创建配置文件。有关手动配置或高级选项，请参阅 examples/：

• config-minimal.yaml — 最精简的配置
• config-power-user.yaml — HTTPS、自定义超时、日志记录、说明
• config-docker.yaml — 由环境变量驱动

完整参考见 docs/specs/config-schema-spec.md。编辑配置文件后，请运行 mcp-synology check --config <file>：该命令会报告 YAML 和验证错误，指出拼写错误的设置项和模块，然后尝试登录。

模块和权限

在 modules: 下启用各个模块，可使用三个键：enabled、permission 和 settings。其他任何键都会导致错误，因此像 permision 这样的拼写错误会让服务停止，而不是被忽略。

• permission 可以是 read（省略时的默认值）或 write。read 只注册模块的 READ 工具；write 会添加其 WRITE 工具。目前也接受 admin，且与 write 相同。它与 DSM 账户无关：管理员账户不需要设置该值。
• settings 保存模块自己的选项（File Station 的选项见下文）。如果模块不认识某个设置，会忽略该设置并发出警告，列出有效设置，因此为较新版本编写的配置仍可加载。
• 未列出的模块不会加载。Download Station 和 Synology Photos 需要选择启用（见上文对应章节）；System 没有写入工具。

连接和 HTTPS

connection:
  host: 192.168.1.100    # or a hostname
  https: true            # default false: credentials then cross the network in cleartext
  port: 5001             # default 5000, or 5001 with https: true
  verify_ssl: false      # default true; false for DSM's default self-signed certificate
  timeout: 30            # seconds per request, 1 to 600 (default 30)

除非 NAS 位于你信任的网络中，否则请使用 https: true：使用普通 HTTP 时，登录信息和每个请求都会以未加密的方式传输，且服务会发出警告日志。除非你选择不启用，否则 setup 会写入 https: true。docs/https.md 介绍 DSM 的自签名证书，以及如何获取受信任的证书。如果 DSM 使用自己的自签名证书，请设置 verify_ssl: false（服务会警告验证已关闭），或者安装此计算机信任的证书，并将该值保持为 true。

多 NAS

每台 NAS 都需要单独的配置文件、凭据和 Claude Desktop 条目。配置文件名可作为自然标识符（例如 home-nas.yaml、media-server.yaml）。

设置 alias，为 Claude 指定此连接的显示名称：

# ~/.config/mcp-synology/home-nas.yaml
alias: HomeNAS

别名会显示在 MCP 服务名称中（例如 synology-HomeNAS），让 Claude 知道自己正在与哪台 NAS 通信。

File Station 设置

File Station 设置放在 filestation 模块的 settings: 下。以下设置均为可选项：

modules:
  filestation:
    enabled: true
    permission: write
    settings:
      delete_timeout: 120        # wait up to 2 minutes before handing a delete off
      copy_move_timeout: 300     # copy, move and restore: 5 minutes
      async_timeout: 180         # search_files and get_dir_size
      allowed_local_paths:
        - ~/Downloads
        - ~/Media
      default_download_dir: ~/Downloads

超时时间以秒为单位（接受 10–3600），按实际经过的时间计算：

设置	默认值	作用
delete_timeout	30	delete_files 等待后移交操作所用的时间。
copy_move_timeout	30	copy_files、move_files 和 restore_from_recycle_bin 等待后移交操作所用的时间。
async_timeout	120	search_files 和 get_dir_size 的时间限制。不适用于删除、复制、移动或还原操作。
search_timeout、dir_size_timeout	async_timeout	search_files 和 get_dir_size 各自的时间限制。超时后，NAS 任务会停止。
upload_timeout、download_timeout	300	upload_file 和 download_file 的时间限制。

对于删除、复制、移动和还原操作，超时时间指的是调用等待后移交操作的时间，而不是操作的时间限制。在等待时间内完成的操作会照常返回结果。尚未完成的操作会继续在 NAS 上运行，回复中会提供一个句柄，例如 delete:FileStation_…，可用于通过 file_task 检查其进度或最终结果，或停止操作。不带句柄调用 file_task 会列出仍在运行的操作。无论设置为何值，等待时间上限均为 600 s，因为 MCP 客户端放弃调用时会取消调用，而被取消的调用会停止操作。

客户端超时。 MCP 客户端有自己的时间限制。对于此类 stdio 服务，Claude Code 默认会在空闲窗口期内未收到结果或进度通知时中止工具调用（HTTP 服务的默认值为 5 分钟）。可通过 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT 环境变量提高此限制（单位为毫秒；0 表示关闭此检查），也可仅为此服务在 MCP 配置条目中设置 timeout 字段（单位为毫秒），该字段还会设置每次调用的硬性上限。请参阅 Claude Code 的 MCP 文档。删除、复制、移动和还原操作在等待期间会发送进度通知，因此不会触及空闲限制。get_dir_size 和 search_files 目前尚不发送进度通知（#252），因此运行时间超过空闲窗口期时，客户端可能会中止调用；请提高客户端的限制或缩小路径范围。

其他设置：

• allowed_local_paths — upload_file 和 download_file 可使用的本地文件夹，包括其子文件夹（默认值：你的 Downloads 文件夹）。顶层的 allowed_local_paths 适用于所有模块，此列表会在其基础上添加路径。如果未设置顶层列表，此列表会取代 Downloads 默认路径。请参阅 Features 中的 本地路径限制。
• default_download_dir — 未提供 dest_folder 时，download_file 使用的本地文件夹。此文件夹始终允许使用。
• default_upload_dir — 未提供 dest_folder 时，upload_file 使用的 NAS 文件夹。
• hide_recycle_in_listings — 从 list_files 的列表中隐藏 #recycle 文件夹（默认值：false）。
• file_type_indicator — 列表中的标记类型，可选 emoji（默认值）或 text。
• search_poll_interval — search_files 在运行时检查 DSM 搜索状态的间隔秒数（默认值：1.0，接受 0.5–10.0）。

完整架构请参阅 docs/specs/config-schema-spec.md，完整配置示例请参阅 examples/config-power-user.yaml。

自定义指令

自定义指令可用于调整 Claude 与 NAS 工具的交互方式。适用于以下场景：

• 多个 NAS 连接 — 告诉 Claude 在不同任务中优先使用哪个连接（“媒体任务用这个连接，跨用户操作用 admin”）
• 安全防护 — 添加“删除前务必确认”或“绝不操作 /Backups”之类的规则
• 上下文 — 说明 NAS 上的内容（“这是媒体服务器，/video 中按类型整理了我们的媒体库”）

添加上下文 — custom_instructions 会添加到内置提示词之前（优先级更高）：

# ~/.config/mcp-synology/config.yaml
custom_instructions: |
  This is the admin NAS with elevated privileges.
  Prefer this connection for file operations requiring cross-user access.
  Never delete files from /Backups without explicit confirmation.

完全控制 — instructions_file 会完全替换内置提示词。从内置文件开始：server.md 会在每次连接时发送，filestation.md 仅在启用 File Station 时发送，filestation-write.md 仅在启用 File Station 的 WRITE 工具（permission: write 或 admin）后发送，而 local.md 会在生成的 LOCAL PATHS 部分之前发送。Synology Photos 部分由 server.py 生成（_PHOTOS_NOTICE，以及在启用 Photos 的 WRITE 工具时生成的 _PHOTOS_WRITE_NOTICE）；如果要使用 Photos，请从 Photos 连接的指令中复制该部分。替换文件会按原样使用，HTML 注释除外，因此不会生成 PERMISSIONS 部分；该部分会告知模型此连接禁用了哪些工具，以及如何启用它们（custom_instructions 会保留该部分）：

# ~/.config/mcp-synology/config.yaml
instructions_file: ~/.config/mcp-synology/my-instructions.md

两者都支持模板变量：{display_name}、{instance_id}、{host}、{port}、{home_dir}（本地 home 文件夹）和 {platform}（Linux、macOS 或 Windows）。其他任何花括号都会按原样保留，因此 JSON 示例可以直接使用（{{ 和 }} 不会作为转义符）。

发送文本前，两者中的 HTML 注释（``）都会被移除，因此可以用它们记录给文件编辑者的备注。单独占一行的注释会连同该行一起移除。

故障排除

错误的 help_url 会指向 docs/error-codes.md 中对应的章节。对于看起来异常但并非错误的行为（下载停留在 waiting 状态、Photos 日期读取时显示旧值、删除操作交接并返回句柄），请参阅按模块组织的 docs/troubleshooting.md。

调试

启用调试日志的两种方法：

mcp-synology check --verbose                          # --verbose flag on setup/check
SYNOLOGY_LOG_LEVEL=debug mcp-synology serve           # env var, works for all commands

或者在配置文件中设置，使其永久生效：

# ~/.config/mcp-synology/config.yaml
logging:
  level: debug
  file: ~/.local/state/mcp-synology/nas/server.log  # optional, logs to stderr by default

调试输出包括每个 DSM API 请求/响应（密码会隐藏）、凭据解析步骤、配置发现、版本协商以及模块注册决策。

贡献

有关构建命令、测试、集成测试设置和设计文档，请参阅 DEVELOPMENT.md。

致谢

本项目采用 规格优先编码 方法构建——这是一种人类与 AI 协作的模式，设计先于实现，规格是双方遵循的契约。

与即兴编码（描述需求并让 AI 随机生成代码）不同，规格优先编码将设计视为独立且有意为之的阶段。docs/specs/ 中的四份原始规格通过长时间的讨论制定而成，期间深入探讨权衡取舍、否决替代方案，并记录决策及其理由。随后，整个实现过程分为 11 个构建阶段，并以规格作为事实依据。

在真实硬件上的实时测试揭示了规格无法预见的行为（DSM API 的一些特殊情况，例如曾被误认为是搜索服务限流的 JSON 解析参数值，以及不兼容的版本格式）。这些发现记录在 CLAUDE.md 和代码中；当规格内容与之不一致时，以它们为准。

License

Apache 2.0

---

© 2026 Chris Means