Skip to main content
Glama
Synology Docker MCP Server

Synology Docker MCP Server

by hifishhe

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)

漏洞

修复方案

密码特殊字符展开($/反引号)

echo "..." 改为 printf '%s\n' '...',避免 shell 展开

命令注入(容器名/项目名/路径拼接)

所有用户输入经 shQuote() 单引号包裹后再拼接命令

action 参数未验证

代码层白名单校验,独立于 schema enum

路径遍历(/etc/shadow 等)

synology_read_file / synology_write_file 限制在 NAS_DOCKER_DIR 内,拒绝含 .. 的路径

tail 参数注入

强制正整数,上限 10000,默认 100

SSH 连接无超时

添加 readyTimeout: 30000

🚀 快速上手配置

  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"
          ]
        }
      }
    }

Related MCP server: QNAP Container Station MCP

🇬🇧 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)

Vulnerability

Fix

Password shell expansion ($, backticks)

Replaced echo "..." with printf '%s\n' '...' to prevent shell expansion

Command injection (container/project name/path concatenation)

All user inputs wrapped with shQuote() before shell concatenation

Unvalidated action parameter

Code-level whitelist enforced independently of schema enum

Path traversal (e.g. reading /etc/shadow)

synology_read_file / synology_write_file restricted to NAS_DOCKER_DIR; paths with .. segments rejected

tail parameter injection

Enforced positive integer, capped at 10000, defaults to 100

SSH connection hangs indefinitely

Added readyTimeout: 30000

🚀 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"
          ]
        }
      }
    }

Available Tools

7 tools
synology_docker_logsB

Get logs for a specific docker container

Inputs: container_name (required), tail.

synology_docker_manageC

Manage container lifecycle (start, stop, restart)

Inputs: action (required), container_name (required).

synology_docker_psA

List all docker containers on the Synology NAS

Inputs: no named parameters.

synology_project_listB

List docker-compose projects in the Synology NAS docker directory

Inputs: no named parameters.

synology_project_manageB

Manage a docker-compose project (up, down, restart)

Inputs: project_name (required), action (required).

synology_read_fileB

Read a configuration file from the NAS (restricted to /volume1/docker)

Inputs: filepath (required).

synology_write_fileA

Write or update a configuration file on the NAS (restricted to /volume1/docker)

Inputs: filepath (required), content (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct operation: container logs, lifecycle, listing; project listing, lifecycle; file read/write. No overlap in functionality.

    Naming Consistency4/5

    All tools share the 'synology_' prefix, but verb placement varies: some are verb_noun (synology_read_file) while others are noun_verb (synology_docker_logs). Mostly consistent with minor deviations.

    Tool Count5/5

    7 tools cover the essential Docker and project management operations without being excessive or sparse. Well-scoped for a NAS-specific server.

    Completeness4/5

    Covers core container and project lifecycle, logs, and file editing. Minor gaps like lack of image management or detailed inspect, but adequate for typical use.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables remote Docker management over SSH via a local MCP server, providing tools to manage containers, images, Compose, and system resources.
      1
      GPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables managing Docker containers and Compose apps on a QNAP NAS via the Container Station API, including starting, stopping, restarting, and inspecting containers and applications.
      9 npm
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables reading Docker container logs and stats from remote servers via SSH, supporting container listing, log retrieval, stats, inspection, and Docker Compose logs.
      -