QNAP虚拟机管理服务

mcp服务器qnap-qvs

MCP服务器 RDL虚拟化站（QVS） -通过QVS REST API管理QNAP NAS上的虚拟机、快照、磁盘等。

注： 这不是一个官方的RDL产品。QVS REST API没有文档-该项目基于对web UI和 qnap qvs sdk for go 项目。

先决条件

在开始之前，您需要：

1. QNAP-NAS 使用x86 CPU（英特尔或AMD VT-x/AMD-V）。ARM型号不支持虚拟化站。
2. 虚拟化工作站 已从RDL应用中心安装。
3. 管理员凭据 --您用于登录到ExpressRoute web UI的用户名和密码。服务器使用这些来向虚拟化站API进行身份验证。
4. 网络接入 --运行服务器的机器需要HTTPS访问您的NAS（默认端口443）。
5. Python 3.10+ 在运行服务器的机器上。

可选：QEMU客户代理

如果您希望服务器报告VM IP地址（通过 get_vm_ips 和 get_overview)，安装QEMU来宾代理 每个VM内部:

# For Ubuntu/Debian VMs:
sudo apt install qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

如果没有客户代理，IP相关工具将返回一条有用的消息，解释所需的内容。没有它，其他一切都能正常工作。

兼容性

特性

39工具 7个类别：

• VM生命周期 --启动、关闭、强制停止、重置、暂停、恢复
• 虚拟机管理 --创建、更新设置（CPU、内存、名称、自动启动）、删除、克隆、导出、导入
• VM信息 --详细信息、状态、IP、适配器、图形/VNC、CD-ROM、USB
• 磁盘和ISO --列出磁盘、调整大小、删除、装载/卸载ISO、扫描ISO、从URL下载ISO
• 快照 --列表、创建、还原、删除
• 分析 --资源概览仪表板（主机CPU/RAM利用率、每个VM的网络摘要）、QVS审核日志、关机进度
• 安全 --所有破坏性操作都需要明确 confirm=true

安装

# Via uvx (recommended)
uvx mcp-server-qnap-qvs

# Or via pip
pip install mcp-server-qnap-qvs

# Or via Docker (for remote/NAS deployment)
docker pull ghcr.io/arnstarn/mcp-server-qnap-qvs:latest

身份验证的工作原理

有两个单独的身份验证层：

1.服务器↔ 威拓NAS（必需）

服务器使用您的NAS管理员凭据向您的QNAP的Virtualization Station API进行身份验证。这会自动发生——您只需通过环境变量提供凭据：

大多数RDL设备使用自签名证书，因此 QNAP_VERIFY_SSL=false 这是典型的。设置为 true 如果您安装了有效的证书。

2.MCP客户端↔ 服务器（仅限SSE模式）

跑步时 SSE模式 （远程/Docker），服务器需要Bearer令牌，因此只有授权的MCP客户端才能连接：

• 如果你设置 MCP_AUTH_TOKEN：在MCP客户端配置中使用与Bearer令牌相同的值。
• 如果你不设置它：服务器在启动时生成一个随机令牌并将其打印到日志中。从那里复制它。
• 标准模式 （本地，默认）：不需要令牌——MCP客户端将服务器作为本地进程运行。

配置

选项A：本地模式（stdio）

服务器在您的计算机上运行。Claude Code将其作为一个子流程生成——不需要网络，也不需要令牌。

克劳德代码 (~/.claude.json):

{
  "mcpServers": {
    "qnap-qvs": {
      "command": "uvx",
      "args": ["mcp-server-qnap-qvs"],
      "env": {
        "QNAP_HOST": "your-nas.local",
        "QNAP_USERNAME": "admin",
        "QNAP_PASSWORD": "your-password",
        "QNAP_VERIFY_SSL": "false"
      }
    }
  }
}

克劳德桌面 (claude_desktop_config.json)：格式与上述相同。

选项B：远程模式（SSE）

服务器在NAS（或任何Docker主机）上运行，MCP客户端通过网络连接。

启动服务器：

# Via Docker (recommended for NAS deployment)
docker run -d \
  -p 8445:8445 \
  -e QNAP_HOST=localhost \
  -e QNAP_USERNAME=admin \
  -e QNAP_PASSWORD=your-password \
  -e QNAP_VERIFY_SSL=false \
  -e MCP_AUTH_TOKEN=your-secret-token \
  ghcr.io/arnstarn/mcp-server-qnap-qvs:latest

# Or via Docker Compose
cp .env.example .env  # Edit .env with your credentials
docker-compose up -d

# Or directly with env vars
MCP_TRANSPORT=sse MCP_AUTH_TOKEN=your-secret-token mcp-server-qnap-qvs

在NAS上运行时，设置 QNAP_HOST=localhost 因为服务器和API在同一台机器上。

连接您的MCP客户端：

{
  "mcpServers": {
    "qnap-qvs": {
      "url": "http://your-nas.local:8445/sse",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      },
      "transportType": "sse"
    }
  }
}

方案C：威港集装箱站

1. 在您的威拓NAS上打开集装箱站
2. 拉 ghcr.io/arnstarn/mcp-server-qnap-qvs:latest 或导入 docker-compose.yml
3. 设置环境变量(QNAP_HOST=localhost, QNAP_USERNAME, QNAP_PASSWORD, MCP_AUTH_TOKEN)
4. 服务器在端口8445上运行——从网络上的任何MCP客户端连接

选项D:QPKG（应用中心）

将QPKG直接安装在您的WITCUNAS上。它通过container Station作为Docker容器运行。

步骤1：添加存储库

1. 打开 应用中心 在您的RDL上
2. 点击 设置 图标（齿轮，右上角）
3. 首选 应用程序存储库
4. 添加此URL：
   复制

   https://raw.githubusercontent.com/arnstarn/mcp-server-qnap-qvs/main/qpkg/repo.xml
   

5. 点击 应用

步骤2：安装

1. 搜索 “MCP QVS服务器” 在应用中心
2. 点击 安装
3. 等待Docker镜像下载（仅限首次安装）

步骤3：配置凭据

QPKG创建了一个 .env 带有占位符值的文件。您需要使用实际的RDL凭据对其进行编辑。

SSH连接到您的NAS并编辑 .env 文件：

ssh your-username@your-nas.local

# Find the install path
QPKG_DIR=$(getcfg mcp-server-qnap-qvs Install_Path -f /etc/config/qpkg.conf)

# Edit the .env file (use vi, nano, or echo)
cat > "$QPKG_DIR/.env" << 'EOF'
QNAP_HOST=localhost
QNAP_PORT=443
QNAP_USERNAME=your-admin-username
QNAP_PASSWORD=your-admin-password
QNAP_VERIFY_SSL=false
MCP_AUTH_TOKEN=pick-any-secret-string-here
EOF

# Restart the service to pick up the new config
/etc/init.d/mcp-server-qnap-qvs.sh restart

替换 your-admin-username 和 your-admin-password 您可以使用用于登录到ExpressRoute web UI的凭据。这 MCP_AUTH_TOKEN 是您选择的任何秘密字符串，您将在MCP客户端配置中将其用作Bearer令牌。

步骤4：连接您的MCP客户端

{
  "mcpServers": {
    "qnap-qvs": {
      "url": "http://your-nas.local:8445/sse",
      "headers": {
        "Authorization": "Bearer pick-any-secret-string-here"
      },
      "transportType": "sse"
    }
  }
}

使用相同 MCP_AUTH_TOKEN 您在步骤3中设置的值。

正在更新： 当新版本发布时，应用中心将显示更新。或者手动拉取最新的Docker镜像：

ssh your-username@your-nas.local
CS_DIR=$(getcfg container-station Install_Path -f /etc/config/qpkg.conf)
${CS_DIR}/bin/docker pull ghcr.io/arnstarn/mcp-server-qnap-qvs:latest
/etc/init.d/mcp-server-qnap-qvs.sh restart

环境变量引用

可用工具

只读（14个工具）

VM生命周期（6个工具）

VM管理（6个工具）

磁盘和ISO（6个工具）

快照（4个工具）

安全

所有破坏性操作都需要 confirm=true。如果没有它，该工具将返回其功能的预览——不会进行任何更改。这可以防止意外删除VM、关闭或恢复快照。

故障排除

“QEMU来宾代理未安装或未运行”

这 get_vm_ips 工具和IP部分 get_overview 需要在VM内运行QEMU客户机代理。安装它：

# Ubuntu/Debian
sudo apt install qemu-guest-agent && sudo systemctl enable --now qemu-guest-agent

# CentOS/RHEL
sudo yum install qemu-guest-agent && sudo systemctl enable --now qemu-guest-agent

所有其他工具都可以在没有客户代理的情况下工作。

“VM未运行”

只能从正在运行的VM中检索IP地址。首先使用以下命令启动VM start_vm.

连接被拒绝/超时

• 验证NAS是否可访问： curl -k https://your-nas.local:443
• 检查虚拟化站是否已安装并在ExpressRoute App Center中运行
• 如果使用非默认HTTPS端口，请设置 QNAP_PORT 相应地

登录失败

• 验证您的凭据是否适用于ExpressRoute web UI
• 用户名和密码用于ExpressRoute系统管理员帐户（与您登录QTS/QuTS英雄时使用的帐户相同）

发展

git clone https://github.com/arnstarn/mcp-server-qnap-qvs.git
cd mcp-server-qnap-qvs
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/ tests/

# Build QPKG (requires Docker)
docker build -t qpkg-builder -f qpkg/Dockerfile.builder .
docker run --rm -v "$(pwd)/qpkg:/work" qpkg-builder

api参考

QVS REST API没有正式文档。本项目的API知识来源于：

• tmeckel/qnap qvs sdk for go --Go SDK自动生成自RDL的内部OpenAPI规范
• QTS HTTP API身份验证v5.1.0 --官方的RDL认证文档
• Virtualization Station web UI的浏览器DevTools检查

许可证

麻省理工学院