Synology Docker MCP Server

(Scroll down for English version / 英文版本在下方)

🇨🇳 中文说明 (Chinese Version)

这是一个专门为群晖 (Synology NAS) 设计的 Model Context Protocol (MCP) 服务器。它旨在通过大语言模型直接管理、配置和调试群晖 Container Manager 中的 Docker 容器和 Docker Compose 项目。

✨ 核心功能与亮点

• 基于 SSH 的安全管理: 直接通过 SSH 与您的群晖 NAS 进行通信，安全执行原生命令，彻底免除对外暴露 Docker TCP 接口的风险。

• 自动提权系统 (Auto-Privilege Escalation): 自动注入凭证静默执行 sudo，完美解决群晖管理员账号在执行 docker 时常见的 Permission Denied 权限壁垒。

• 群晖 Container Manager 完美兼容: 原生支持并强制使用 docker-compose -p 标签，确保通过此 MCP 服务器启动或更新的项目能够与群晖自带网页端的项目界面完美同步（维持绿点健康状态）。

• 全方位工具集:

  • synology_docker_ps: 查看所有运行中的容器。

  • synology_docker_logs: 获取并追踪容器日志。

  • synology_docker_manage: 控制容器的启动、停止、重启或移除。

  • synology_project_list: 自动搜索并发现 /volume1/docker/ 目录下的所有项目。

  • synology_project_manage: 原生执行项目的 Pull、Up、Down 或 Restart 指令。

  • synology_read_file / synology_write_file: 远程读取或修改 .env 与 docker-compose.yml 配置文件。

🔒 安全加固记录 (v1.1.0)

🚀 快速上手配置

1. 开启群晖 SSH 服务: 前往 控制面板 -> 终端机和 SNMP 并勾选 启动 SSH 功能。

2. 配置环境变量凭证: 复制项目中的 .env.example 并重命名为 .env，填入您的 NAS 连接信息：

   NAS_HOST=192.168.1.xxx
   NAS_PORT=22
   NAS_USER=your_admin_account
   NAS_PASSWORD=your_admin_password
   NAS_DOCKER_DIR=/volume1/docker

3. 安装依赖并构建:

   npm install
   npm run build

4. 接入 MCP 客户端 (例如 Claude Desktop 或 Cursor): 将以下内容添加到客户端的 MCP 配置文件 JSON 中：

   {
     "mcpServers": {
       "synology-docker": {
         "command": "node",
         "args": [
           "--env-file=e:\\Dev\\Synology Docker MCP\\.env",
           "e:\\Dev\\Synology Docker MCP\\build\\index.js"
         ]
       }
     }
   }

🇬🇧 English Version

This is a Model Context Protocol (MCP) server specifically designed to manage, configure, and debug Docker containers and Docker Compose projects on Synology NAS devices.

✨ Features & Highlights

• SSH-Based Management: Communicates with your Synology NAS directly via SSH, ensuring secure execution of native commands without needing to expose the Docker TCP socket.

• Auto-Privilege Escalation: Automatically injects credentials to run sudo silently, bypassing the Permission Denied issues commonly faced by Synology administrator accounts.

• Synology Container Manager Compatibility: Native support for docker-compose -p, ensuring that projects started or updated via this MCP server perfectly align with the Synology Container Manager GUI (maintaining the green status indicator).

• Comprehensive Toolset:

  • synology_docker_ps: View all running containers.

  • synology_docker_logs: Stream container logs.

  • synology_docker_manage: Start, stop, restart, or remove containers.

  • synology_project_list: Discover projects mapped in /volume1/docker/.

  • synology_project_manage: Pull, up, down, or restart Docker Compose projects natively.

  • synology_read_file / synology_write_file: Edit .env and docker-compose.yml configurations remotely.

🔒 Security Hardening (v1.1.0)

🚀 Setup Instructions

1. Enable SSH on Synology NAS: Go to Control Panel -> Terminal & SNMP and check Enable SSH service.

2. Configure Credentials: Copy .env.example to .env and fill in your NAS connection details:

   NAS_HOST=192.168.1.xxx
   NAS_PORT=22
   NAS_USER=your_admin_account
   NAS_PASSWORD=your_admin_password
   NAS_DOCKER_DIR=/volume1/docker

3. Install Dependencies & Build:

   npm install
   npm run build

4. Connect to MCP Client (e.g. Claude Desktop / Cursor): Add the following to your MCP configuration JSON:

   {
     "mcpServers": {
       "synology-docker": {
         "command": "node",
         "args": [
           "--env-file=e:\\Dev\\Synology Docker MCP\\.env",
           "e:\\Dev\\Synology Docker MCP\\build\\index.js"
         ]
       }
     }
   }