内容
<div align="center">
<img src="docs/assets/banner.svg" alt="群晖MCP服务器" width="100%" />
# 群晖MCP服务器
**通过任何MCP客户端监控和管理群晖DSM 7 NAS，并在聊天中构建实时仪表盘。**
[](https://www.python.org/)
[](https://modelcontextprotocol.io)
[](LICENSE)
[](https://www.synology.com/dsm)
[](docs/TOOLS.md)
[](https://github.com/rafalr100/synology-mcp/actions/workflows/ci.yml)
</div>
一个 [模型上下文协议](https://modelcontextprotocol.io) (MCP) 服务器，为LLM客户端（如 **Claude**）提供 **71种工具**，用于监控和管理群晖DSM 7 NAS：系统健康、存储和磁盘、文件、Docker、虚拟机、软件包、DSM更新、下载站、超备份、用户、服务、安全、证书等 - 以及一个一键快照，用于渲染 **漂亮的仪表盘** 作为制品。
它使用官方DSM Web API（`entry.cgi`），处理登录（包括2FA通过持久化受信任设备令牌），缓存会话并自动重新认证。
> **在DSM 7.3.2上测试**（DS423+）。大多数工具使用稳定的核心API，适用于DSM 7.x。
---
## 目录
- [什么是MCP服务器？](#什么是MCP服务器？)
- [如何协同工作](#如何协同工作)
- [功能](#功能)
- [快速入门](#快速入门)
- [配置](#配置)
- [环境变量](#环境变量)
- [双因素认证](#双因素认证-2FA)
- [连接MCP客户端](#连接MCP客户端)
- [Claude Desktop](#Claude-Desktop)
- [Claude Code](#Claude-Code)
- [仪表盘和技能](#仪表盘和技能)
- [使用示例](#使用示例)
- [工具参考](#工具参考)
- [架构](#架构)
- [安全](#安全)
- [故障排除](#故障排除)
- [FAQ](#FAQ)
- [贡献](#贡献)
- [许可证](#许可证)
---
## 什么是MCP服务器？
[模型上下文协议](https://modelcontextprotocol.io)（MCP）是一种开放标准，允许AI助手以统一的方式与外部工具和数据源通信。 **MCP服务器** 通过简单协议公开一组 *工具*（模型可以调用的函数）； **MCP客户端**（您聊天的应用程序，例如Claude Desktop）连接到服务器，并让模型代表您调用这些工具。
可以把它看作 **AI和软件之间的通用适配器**：模型不需要猜测，而是调用一个返回真实数据的真实函数。
**该项目是您群晖NAS的MCP服务器。** 它将类似 *“我的存储空间有多满？”* 或 *“重启Home Assistant容器”* 的普通请求转换为经过身份验证的群晖DSM API调用，并将结构化结果返回给模型 - 然后模型会回答您或渲染仪表盘。
```
您 ──▶ Claude（MCP客户端） ──▶ 群晖MCP服务器 ──▶ DSM Web API ──▶ 您的NAS
▲ │
└────────────── 结果/仪表盘 ◀───────────────────┘
```
您不需要了解任何API细节 - 只需安装服务器，将其指向您的NAS，连接您的客户端，并用自然语言询问。
## 如何协同工作
```mermaid
flowchart LR
U["👤 您"] -->|自然语言| C["🤖 Claude<br/>(MCP客户端)"]
C -->|工具调用| S["⚙️ 群晖MCP服务器<br/>71种工具"]
S -->|HTTPS entry.cgi| D["🟦 群晖DSM 7 API"]
D --> N["🗄️ 您的NAS<br/>存储 · Docker · 虚拟机 · 用户 …"]
N -->|JSON| S
S -->|结构化结果| C
C -->|答案或 📊 仪表盘| U
```
服务器认证一次（可选2FA通过受信任的设备令牌），缓存会话，并在会话过期时自动重新认证。
---
## 功能
- **71种工具**，涵盖21个领域 - 参见完整的 [工具参考](docs/TOOLS.md)。
- **监控：** 系统信息、CPU/RAM/网络负载、健康状况、连接、进程。
- **存储：** 卷、存储池、每个磁盘的S.M.A.R.T.和温度。
- **文件：** 浏览、搜索、信息、目录大小、MD5、创建/重命名/复制/移动/删除、提取存档、公共共享链接。
- **应用：** Docker（容器、镜像、项目、日志、实时统计、启动/停止/重启）、虚拟机管理器、下载站、超备份、任务调度器、监视站（摄像头）、群晖照片和群晖Drive。
- **管理：** 软件包和DSM更新、用户/组、共享文件夹（创建/删除）、文件服务（SMB/AFP/NFS/FTP）、SSH/SNMP、硬件/UPS、安全、证书、DDNS、QuickConnect、通知、日志、安全扫描。
- **仪表盘：** `get_overview` 通过一次调用返回完整快照；捆绑的 [技能](skills/synology-nas) 教导客户端如何渲染它为精美的HTML仪表盘。
- **设计安全：** 状态更改工具标记为 `control`；破坏性操作（重启/关闭/DSM更新） **除非明确启用，否则禁用**。
- **无硬编码秘密：** 所有凭证来自环境变量/`.env`。
---
## 快速入门
### 选项A - 有指导的设置（推荐）
一个交互式脚本创建环境，询问您的NAS详细信息，处理2FA，测试连接，并为您在Claude Desktop上注册服务器：
```bash
git clone https://github.com/rafalr100/synology-mcp.git
cd synology-mcp
python3 configure.py
```
然后完全退出并重新打开Claude Desktop。就这样。
### 选项B - 手动
```bash
# 1. 克隆
git clone https://github.com/rafalr100/synology-mcp.git
cd synology-mcp
# 2. 安装（推荐使用uv）
uv venv --python 3.12 .venv
uv pip install --python .venv -e .
# … 或： python3 -m venv .venv && .venv/bin/pip install -e .
# 3. 配置
cp .env.example .env # 然后编辑 URL / 用户名 / 密码
# 4. （仅当您的帐户使用2FA时）获取设备令牌
.venv/bin/python bootstrap_2fa.py 123456 # 123456 = 当前OTP代码
# 5. 验证
.venv/bin/python smoke_test.py
```
然后 [将其连接到客户端](#连接MCP客户端)。
---
## 配置
### 步骤1 - 准备NAS
1. **查找NAS地址和端口。** 在DSM中： *控制面板 → 网络 → 网络接口* （或您的路由器）。默认Web API端口是 **5000** （HTTP）/ **5001** （HTTPS）。您的URL将类似于 `http://192.168.1.100:5000`。
2. **（推荐）创建专用用户。** *控制面板 → 用户和组 → 创建*。仅授予必要的访问权限（您要管理的应用程序和共享文件夹）。管理员组权限对于某些工具是必需的（存储、用户、服务、证书、电源）。
3. **2FA？** 如果帐户启用了双因素身份验证，请准备好您的身份验证器应用程序，以便进行 [步骤4](#双因素认证-2FA)。DSM Web API本身默认启用 - 无需开启其他功能。
### 步骤2 - 创建您的`.env`
将`.env.example`复制到`.env`并填写：
```ini
SYNOLOGY_URL=http://192.168.1.100:5000
SYNOLOGY_USER=您的用户名
SYNOLOGY_PASS=您的密码
```
### 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|----------|:--------:|---------|-------------|
| `SYNOLOGY_URL` | ✅ | `http://localhost:5000` | NAS的基本URL（使用 `https://…:5001` 进行TLS） |
| `SYNOLOGY_USER` | ✅ | — | DSM用户名 |
| `SYNOLOGY_PASS` | ✅ | — | DSM密码 |
| `SYNOLOGY_DEVICE_ID` | 仅限2FA | — | 受信任的设备令牌（来自 `bootstrap_2fa.py`） |
| `SYNOLOGY_OTP` | — | — | 一次性OTP（仅限引导；优先使用设备令牌） |
| `SYNOLOGY_VERIFY_SSL` | — | `false` | 验证TLS证书 |
| `SYNOLOGY_TIMEOUT` | — | `30` | HTTP超时（秒） |
| `SYNOLOGY_SESSION_NAME` | — | `SynologyMCP` | DSM中显示的会话名称 |
| `SYNOLOGY_DEVICE_NAME` | — | `SynologyMCP` | DSM中显示的设备名称 |
| `SYNOLOGY_ENABLE_POWER_CONTROL` | — | `false` | 允许 `reboot_nas` / `shutdown_nas` / `install_dsm_update` |
详见 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)。
### 步骤3 - 登录工作原理
```mermaid
flowchart TD
A["服务器启动"] --> B{"设置了SYNOLOGY_DEVICE_ID?"}
B -->|是| C["使用密码 + 设备令牌登录"]
B -->|否| E{"设置了SYNOLOGY_OTP?"}
E -->|是| F["使用密码 + OTP（一次性）登录"]
E -->|否| G["仅使用密码登录"]
C --> H["✅ 会话缓存"]
F --> H
G --> H
H --> I["会话过期时自动重新登录"]
```
### 双因素认证（2FA）
如果您的帐户启用了2FA，则单凭密码无法登录。兑换 **一个** OTP代码以获取 **持久的受信任设备令牌**（这样您就不再需要OTP）：
```bash
.venv/bin/python bootstrap_2fa.py 123456 # 当前6位代码来自您的身份验证器
```
这将 `SYNOLOGY_DEVICE_ID=…` 追加到您的 `.env`。如果令牌被无效（例如密码更改后），只需使用新的OTP代码重新运行引导程序。
---
## 连接MCP客户端
> 服务器在本地运行，通过LAN与NAS通信。它与本地客户端（Claude Desktop，Claude Code）一起工作。 **无法** 从 claude.ai 网页应用访问， claude.ai 的云服务器无法访问您的本地网络。
### Claude Desktop
编辑配置文件：
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"synology": {
"command": "/absolute/path/to/synology-mcp/.venv/bin/python",
"args": ["-m", "synology_mcp"],
"env": {
"PYTHONPATH": "/absolute/path/to/synology-mcp",
"SYNOLOGY_URL": "http://192.168.1.100:5000",
"SYNOLOGY_USER": "您的用户名",
"SYNOLOGY_PASS": "您的密码",
"SYNOLOGY_DEVICE_ID": "您的设备令牌（如果启用2FA）"
}
}
}
}
```
完全退出并重新打开Claude Desktop - 群晖工具将出现在工具菜单中。
一个可编辑的副本位于 [`examples/claude_desktop_config.example.json`](examples/claude_desktop_config.example.json)。
### Claude Code
```bash
claude mcp add synology -- /absolute/path/to/synology-mcp/.venv/bin/python -m synology_mcp
```
… 或在工作目录中放入项目范围的 [`.mcp.json`](.mcp.json.example)。
> **提示：** 仅在 `.env` 中保留凭证 - 服务器自动从其自己的目录加载它，因此可以在客户端配置中省略 `env` 块。
---
## 仪表盘和技能
要求客户端 *“一个NAS仪表盘”*，它将调用 **`get_overview`** （一次往返调用系统、负载、存储、磁盘和工作负载计数），并渲染一个 **自包含的HTML仪表盘** 作为制品。
仓库附带了一个 [Claude技能](skills/synology-nas)（`skills/synology-nas/SKILL.md`），教导客户端何时使用哪个工具以及如何渲染仪表盘 - 包括 [设计指南](skills/synology-nas/references/dashboard_design.md) 和 [HTML模板](skills/synology-nas/assets/dashboard_template.html)。参见 [docs/DASHBOARDS.md](docs/DASHBOARDS.md)。
---
## 使用示例
连接后可以使用的自然语言提示：
- *“给我一个NAS概览/仪表盘。”*
- *“我的存储空间有多满，哪些磁盘是健康的？”*
- *“是否有DSM更新可用？哪些Docker镜像可以更新？”*
- *“显示正在运行的容器并重启 `homeassistant`。”* （询问确认）
- *“列出虚拟机及其状态。”*
- *“当前有哪些连接，显示最后10条系统日志记录。”*
- *“在 `/home` 中搜索 `*.pdf` 并告诉我 `/docker` 的大小。”*
- *“SSH和SMB是否启用？我的DDNS主机名和证书过期时间是多少？”*
更多示例请参见 [examples/prompts.md](examples/prompts.md)。
---
## 工具参考
所有 **71种工具** 都已记录 - 包括参数和返回值 - 在 ** [docs/TOOLS.md](docs/TOOLS.md)** 中。按领域分类：
| 领域 | 工具 |
|--------|-------|
| 仪表盘 | `get_overview` |
| 系统监控 | `get_system_info`, `get_resource_usage`, `get_network_info`, `get_resource_history` |
| 健康和活动 | `get_system_health`, `get_active_connections`, `list_processes`, `get_time_settings` |
| 存储 | `get_storage_info`, `get_storage_pools`, `get_disk_info` |
| 文件 | `list_shares`, `list_files`, `get_file_info`, `get_directory_size`, `get_file_md5`, `search_files`, `create_folder`, `rename_item`, `copy_move_item`, `delete_item`, `extract_archive`, `create_share_link` |
| 软件包和更新 | `check_dsm_update`, `list_packages`, `set_package_state` |
| Docker | `list_containers`, `get_container_logs`, `get_container_stats`, `list_docker_projects`, `list_docker_images`, `set_container_state` |
| 虚拟机 | `list_virtual_machines`, `set_vm_state` |
| 监视站 | `get_surveillance_info`, `list_cameras` |
| 群晖照片 | `list_photo_albums` |
| 群晖Drive | `list_drive_connections` |
| 下载站 | `list_downloads`, `add_download`, `manage_download` |
| 备份 | `list_backup_tasks`, `run_backup_task` |
| 任务调度器 | `list_scheduled_tasks`, `run_scheduled_task` |
| 用户和共享 | `list_users`, `list_groups`, `list_shared_folders`, `create_shared_folder`, `delete_shared_folder` |
| 服务 | `get_file_services`, `set_file_service`, `get_terminal_settings`, `get_snmp_settings` |
| 硬件 | `get_power_settings`, `get_hibernation_settings`, `get_ups_status`, `list_usb_devices` |
| 安全 | `get_security_settings`, `get_autoblock_settings`, `get_firewall_status`, `list_certificates` |
| 网络服务 | `get_ddns_status`, `get_quickconnect_status` |
| 通知 | `get_notification_settings` |
| 日志和扫描 | `get_system_logs`, `get_security_scan_status` |
| 电源（需选择） | `reboot_nas`, `shutdown_nas`, `install_dsm_update` |
---
## 架构
```
synology_mcp/
├── config.py # 环境变量/ .env 中的设置（无硬编码秘密）
├── api.py # 异步DSM客户端：登录、2FA、会话、自动重新认证
├── app.py # 共享的FastMCP实例 + 格式化帮助程序
├── server.py # 入口点（python -m synology_mcp）
└── tools/ # 每个域一个模块；导入注册工具
├── dashboard.py monitoring.py system.py storage.py
├── files.py packages.py docker.py virtualization.py
├── downloads.py backup.py scheduler.py admin.py
├── services.py hardware.py security.py network_services.py
├── notifications.py power.py
skills/synology-nas/ # Claude技能：工具指导 + 仪表盘渲染
docs/ # TOOLS.md, CONFIGURATION.md, DASHBOARDS.md
examples/ # 客户端配置 + 示例提示
```
每次调用都通过DSM `entry.cgi`网关；API版本已针对DSM 7.3.2系统进行验证。添加工具：在`synology_mcp/tools/`下的模块中编写`@mcp.tool()`异步函数，并将模块添加到`tools/__init__.py`。
---
## 安全
- **凭证存储在 `.env` / 客户端配置中，而非代码中。** `.env` 和 `.mcp.json` 被git忽略。
- 优先使用 **专用的DSM帐户**，仅具有必要的权限，而非主要管理员帐户。
- 适用于 **受信任的本地网络**使用。
- **电源操作需选择**，通过 `SYNOLOGY_ENABLE_POWER_CONTROL=true`。
- HTTP客户端禁止请求日志记录，因此凭证不会到达stderr。
---
## 故障排除
| 症状 | 原因/解决方法 |
|---------|-------------|
| `auth failed (code 400)` | 用户名或密码错误。 |
| `auth failed (code 403/406)` | 帐户启用2FA - 运行 `python bootstrap_2fa.py <OTP>` 获取设备令牌。 |
| 启用2FA后 `auth failed (code 400)` | OTP过期（30秒窗口）- 使用新代码重新运行引导程序。 |
| `Synology API error (code 105)` | 您的帐户缺乏该操作的权限（使用管理员帐户）。 |
| `Synology API error (code 119)` | 会话过期 - 自动处理；如果持续，重启服务器。 |
| Claude Desktop中未显示工具 | 完全 **退出** （而非关闭）并重新打开；检查路径配置以及 `command` 路径是否为绝对路径。 |
| `ModuleNotFoundError: synology_mcp` | 在客户端 `env` 中设置 `PYTHONPATH` 至仓库根目录，或 `pip install -e .`。 |
| 连接超时 | 检查 `SYNOLOGY_URL` /端口以及NAS是否可达；提高 `SYNOLOGY_TIMEOUT`。 |
| TLS证书错误 | 使用 `http://…:5000`，或为自签名证书设置 `SYNOLOGY_VERIFY_SSL=false`（默认）。 |
| 工具错误 | 该软件包/功能可能未安装/启用（例如VMM、Docker、UPS、DDNS）。 |
---
## FAQ
**是否适用于 claude.ai 网站或移动应用？**
否 - 它们运行在Anthropic的云中，无法访问您局域网上的NAS。使用本地客户端（Claude Desktop / Claude Code）。对于远程访问，您需要VPN（例如Tailscale）和远程MCP传输，这超出了此处范围。
**支持哪些DSM版本？**
构建并测试于 **DSM 7.x** （7.3.2）。DSM 6使用旧API路径，不受支持。
**是否安全？可以删除我的数据吗？**
读取工具是安全的。状态更改工具标记为 `control`；行为良好的客户端在执行前会确认。对于重启/关闭/更新，需要明确选择。
**是否存储密码？**
仅存储在 `.env` 或客户端配置中，这两者都是您本地机器上的。
**无需2FA可以运行吗？**
可以。2FA是可选的；如果没有2FA，仅需用户名+密码即可。
---
## 路线图
计划添加的内容（监视站、群晖照片和Drive、更丰富的日志、时间和NTP等）都在 [docs/ROADMAP.md](docs/ROADMAP.md) 中跟踪。
## 贡献
欢迎提出问题和拉取请求 - 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
---
## 许可证
[MIT](LICENSE).
> 不隶属于或得到群晖公司的任何认可。“群晖”和“DSM”是其各自所有者的商标。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器