mcp-synology

用于 Synology NAS 设备的 MCP 服务器。将 Synology DSM API 功能公开为 Claude 可以使用的 MCP 工具。

从 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 上的文件。跨两个权限层级的 14 个工具：

• 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

系统

监控 NAS 健康状况和资源利用率。2 个只读工具：

• get_system_info — 型号、固件版本、内存、温度、运行时间（适用于所有用户）

• get_resource_usage — 实时 CPU 负载、内存使用率、磁盘 I/O、网络吞吐量（需要管理员账户）

功能

• 交互式设置 — 指导式配置，用于创建配置、存储凭据、处理 2FA 并生成 Claude Desktop 代码片段

• 权限分级 — 每个模块的 READ 或 WRITE 权限，在工具注册时强制执行

• 2FA 支持 — 自动检测；设备令牌引导，支持自动静默重新认证

• 安全凭据 — 操作系统密钥环集成，在 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 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

2FA 支持

mcp-synology 完全支持启用了双重身份验证的 DSM 账户。它是自动检测的，您无需进行任何特殊配置：

1. 引导 — mcp-synology setup 检测到 2FA，提示输入 OTP 代码，并将设备令牌存储在密钥环中

2. 静默重新认证 — 后续登录会自动使用设备令牌（无需 OTP 提示）

3. 实例隔离 — 每个 NAS 配置都有自己的设备令牌，因此混合使用 2FA/非 2FA 设置完全没问题

设备令牌会一直保留，直到您在 DSM 中明确撤销它们（个人 > 安全 > 登录活动）。它们不会自动过期。如果令牌被撤销，请再次运行 mcp-synology setup 进行重新引导。

密钥环与凭据

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

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

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

请参阅 docs/credentials.md 了解密钥环服务名称、多 NAS 设置以及如何检查/删除存储的凭据。

更新

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 — 环境变量驱动

多 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 通信。

自定义指令

自定义指令允许您塑造 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 作为起点：

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

两者都支持模板变量：{display_name}, {instance_id}, {host}, {port}。

调试

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

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 了解构建命令、测试、集成测试设置和设计文档。

致谢

本项目采用 Spec-First Coding（规范优先编码） 方法构建——这是一种人机协作模型，设计先于实现，规范是两者之间的契约。

与“氛围编码（vibe coding）”不同（即描述需求并让 AI 即时生成代码），规范优先编码将设计视为一个独立、审慎的阶段。docs/specs/ 中的四个规范是通过长时间的对话开发的——探索权衡、拒绝替代方案并记录带有理由的决策。实现阶段则在 11 个构建阶段中将规范作为事实来源。

针对真实硬件的实时测试揭示了规范无法预料的行为（DSM API 怪癖、搜索服务限流、版本格式不兼容）。这些发现记录在 CLAUDE.md 和代码中，在规范存在分歧时，以代码为准。

许可证

Apache 2.0