synology-mcp

# synology-mcp 一个 [MCP](https://modelcontextprotocol.io/) 服务器，封装了 Synology DSM 的网络 API，以便 AI 代理（Claude Code、Claude Desktop、IDE 助手）可以管理 Synology NAS 设备，而无需在每个任务中重新发现 DSM 的特殊之处。 **状态：** 测试版。功能完整的最小可行产品 — 8 个模块（身份验证、RAID、网络、软件包、用户主目录、共享、快照复制、SSH）提供了 28 种工具，涵盖只读检查和支持的写入操作。目前，针对 DSM 7.3.2 的 187 个单元测试和 24 个实时集成测试均已通过。API 稳定；已记录的 v0 限制：不支持跨用户 SSH 写入（需要 sudo 密码机制），不支持软件包安装的离线 `.spk` 回退。请参阅 [DESIGN.md](DESIGN.md) 以获取完整的架构、工具表面和 DSM API 映射。 ## 为什么 DSM 的网络 API 有一些众所周知的特殊之处： - 身份验证握手使用 `account=`（而不是 `username=`），版本 6 的 `SYNO.API.Auth`，响应同时携带 `sid` cookie 和 `X-SYNO-TOKEN` 头部，必须在后续调用中一起发送。 - 通过文档化的端点启用 **用户主目录**，在 DSM 7.3 上静默无效，除非 `/etc/synoinfo.conf` 已经包含 `userHomeEnable=yes`。 - 通过 `SYNO.Core.Package.Installation install_from_server` 安装某些软件包会因不明原因而失败，但如果直接上传 `.spk` 文件，则可以正常工作。 - **快照复制** 计划创建受到一次性 UI 仅限节点配对向导的限制；可以通过 API 读取计划状态，但无法从冷启动创建计划。 - SFTP 子系统默认禁用 — `paramiko.open_sftp()` 返回 `Channel closed`。文件传输必须使用 `scp`、`rsync` 或 base64-over-`exec`。 - DSM 的软件包状态报告器 (`synopkg status`) 对 ContainerManager 撒谎（声称 `stop`，而 Docker 正在健康运行）。 `synology-mcp` 将这些特殊之处封装起来，以便您的代理无需处理它们。 ## 范围 ### 最小可行产品（正在积极设计中） 1. **身份验证流程** — 登录 → `sid` + `syno_token`，自动刷新，按主机缓存会话。 2. **软件包管理** — 安装（带有 `install_from_server`-fails-fallback-to-`.spk`），列表，状态，卸载。 3. **启用用户主目录** — 在一次工具调用中应用 `synoinfo.conf` + 符号链接重定向 + `synouserhome --prepare-folder` 变通方法。 4. **快照复制** — **只读**（列表计划，状态，近期活动）。计划创建被推迟；请参阅 [DESIGN.md §11](DESIGN.md#11-out-of-scope-for-mvp)。 5. **共享文件夹生命周期** — 创建，列表，ACL 读取，快照配置读取。 6. **RAID / 卷 / 磁盘检查** — 表面 `/proc/mdstat`，`synodisk`，`syno_dsm_serial`，`volume*` fs/usage。 7. **SSH 密钥 + 端口管理** — 将公钥放入 `authorized_keys`，设置 SSH 端口，启用用户应用程序 SSH 权限。 8. **网络基础** — eth 接口状态，MTU，MAC。 ### 超出范围（暂时） - 快照复制计划创建（UI 受限） - 加密密钥管理 - TLS 证书轮换 - DSM 更新编排 - 超级备份 - 软件包市场搜索 有关理由，请参阅 [DESIGN.md §11](DESIGN.md#11-out-of-scope-for-mvp)。 ## 多主机 每个工具都接受一个 `host` 参数。凭证和连接设置来自配置文件或环境变量 — 此代码库中**没有硬编码主机**。请参阅 [`examples/config.toml`](examples/config.toml)。 ## 快速入门 > 实施中 — 本部分是预期的用户体验。 ```bash # 从 PyPI 安装（发布后） uv tool install synology-mcp # 或从源代码运行 git clone https://github.com/acato/synology-mcp cd synology-mcp uv sync uv run synology-mcp ``` ### Windows：避免 Microsoft Store Python 如果 `uv` 在创建虚拟环境时选择了 Microsoft Store Python（路径在 `\WindowsApps\PythonSoftwareFoundation...` 下），则 MCP 可以从终端正常运行，但无法从 GUI 主机（如 Claude 桌面应用程序、IDE 扩展或计划任务）启动。您将看到： ``` Unable to create process using "...\WindowsApps\PythonSoftwareFoundation.Python.3.12_...\python.exe" ``` Store-Python 应用程序执行别名需要交互式用户上下文，而 GUI 生成的子进程无法获得。固定 `uv` 到非 Store 解释器 — uv 的托管 Python 最简单： ```powershell uv python install 3.12 uv venv --python 3.12 --python-preference only-managed --clear uv sync ``` 验证：`Get-Content .venv\pyvenv.cfg` — `home =` 行应指向 `AppData\Roaming\uv\python\...` 下，而不是 `\WindowsApps\`。python.org 安装程序或 `winget install Python.Python.3.12` 也有效。 ### 连接到 Claude Code ```bash claude mcp add synology-mcp -- uv run --directory /path/to/synology-mcp synology-mcp ``` ### 配置 复制 `examples/config.toml` 到 `~/.config/synology-mcp/config.toml` 并填写您的主机。或者，设置每主机的环境变量（请参阅 [DESIGN.md §6](DESIGN.md#6-configuration)）。 ## 文档 - [DESIGN.md](DESIGN.md) — 完整的架构和工具表面 - [CONTRIBUTING.md](CONTRIBUTING.md) — 如何贡献 - [`examples/`](examples/) — 示例配置 ## 兼容性 - **DSM 7.3** — 一流目标（DSM 7.3.2 build 86009 参考） - **DSM 7.2** — 设计包括一个薄兼容层；一旦 7.3 稳定后将进行测试 - **DSM 6.x** — 超出范围（EOL） 有关兼容性策略，请参阅 [DESIGN.md §9](DESIGN.md#9-versioning--dsm-compatibility)。 ## 许可证 [Apache License 2.0](LICENSE)。请参阅 [NOTICE](NOTICE) 以获取致谢信息。 ## 商标 本项目与 Synology Inc. 无关，也未得到其认可或赞助。“Synology”和“DSM”是 Synology Inc. 的商标。