VergeOS MCP Server

VergeOS MCP服务器

一种用于交互的模型上下文协议（MCP）服务器 VergeOS 虚拟化平台。这使得像Claude、Windsurf/Cascade和其他MCP兼容客户端这样的AI助手能够通过自然语言管理VM、网络、租户和监控您的VergeOS集群。

架构概述

此项目提供了两种部署选项：

┌─────────────────────────────────────────────────────────────────────────────┐
│                           DEPLOYMENT OPTIONS                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  Option 1: Local (stdio)              Option 2: Remote (HTTP + Local Proxy) │
│  ─────────────────────────            ───────────────────────────────────── │
│                                                                              │
│  ┌──────────┐    stdio    ┌─────────┐     ┌──────────┐   HTTP   ┌─────────┐│
│  │ Windsurf │◄──────────►│  MCP    │     │ Windsurf │◄────────►│  Local  ││
│  │ /Claude  │            │ Server  │     │ /Claude  │  stdio   │  Proxy  ││
│  └──────────┘            └────┬────┘     └──────────┘          └────┬────┘│
│                               │                                      │     │
│                               │ HTTPS                          HTTPS │     │
│                               ▼                                      ▼     │
│                          ┌─────────┐                          ┌──────────┐ │
│                          │VergeOS │                          │ K8s MCP  │ │
│                          │  API   │                          │ Server   │ │
│                          └─────────┘                          └────┬─────┘ │
│                                                                    │       │
│                                                               HTTPS│       │
│                                                                    ▼       │
│                                                              ┌──────────┐  │
│                                                              │ VergeOS  │  │
│                                                              │   API    │  │
│                                                              └──────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

何时使用每个选项

特性

MCP工具

VM电源控制

虚拟机配置

网络管理

租户管理

集群和节点管理

存储和监控

快照管理

智能功能

• 优雅的关机与等待: power_off_vm 可以等待VM关闭，并在超时后自动强制执行
• 正在运行VM处理: modify_vm 检测正在运行的虚拟机，并可以自动关闭以应用CPU/RAM更改
• 日志过滤：按级别筛选日志(error, warning, audit)或对象类型(vm, node, vnet)
• 快照过期: create_vm_snapshot 支持自动过期（默认7天）
• 静止快照：在快照之前暂停VM的选项（需要来宾代理）

MCP资源

• vergeos://cluster/status -集群状态概述
• vergeos://vms/list -所有虚拟机
• vergeos://networks/list -所有虚拟网络
• vergeos://alarms/active -主动系统报警

______________________________________________________________________

选项1：本地安装（stdio）

如果您的AI客户端运行在可以直接访问您的VergeOS实例的机器上，请使用此选项。

安装

git clone  vergeos-mcp-server
cd vergeos-mcp-server
npm install

配置

创建一个 .env 文件：

VERGEOS_HOST=your-vergeos-host
VERGEOS_USER=admin
VERGEOS_PASS=your-password

或者使用API令牌（推荐）：

# Get a token
curl -sk -X POST "https://your-vergeos-host/api/sys/tokens" \
  -u "admin:password" \
  -H "Content-Type: application/json" \
  -d '{"login":"admin","password":"password"}' | jq -r '."$key"'

# Set in .env
VERGEOS_HOST=your-vergeos-host
VERGEOS_TOKEN=your-token-here

Claude桌面配置

添加到 ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vergeos": {
      "command": "node",
      "args": ["/path/to/vergeos-mcp-server/src/index.js"],
      "env": {
        "VERGEOS_HOST": "your-vergeos-host",
        "VERGEOS_USER": "admin",
        "VERGEOS_PASS": "your-password"
      }
    }
  }
}

风帆配置

添加到 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "vergeos": {
      "command": "node",
      "args": ["/path/to/vergeos-mcp-server/src/index.js"],
      "env": {
        "VERGEOS_HOST": "your-vergeos-host",
        "VERGEOS_USER": "admin",
        "VERGEOS_PASS": "your-password"
      }
    }
  }
}

______________________________________________________________________

选项2：远程安装（Kubernetes+本地代理）

如果您的AI客户端（例如笔记本电脑上的Windsurf）无法直接访问VergeOS，但您有一个可以访问的Kubernetes集群，请使用此功能。

建筑

┌─────────────┐      ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Windsurf  │─────►│ Local Proxy │─────►│  K8s MCP    │─────►│   VergeOS   │
│  (Laptop)   │stdio │  (Laptop)   │HTTPS │  Server     │HTTPS │    API      │
└─────────────┘      └─────────────┘      └─────────────┘      └─────────────┘
                                                │
                                          ┌─────┴─────┐
                                          │  Traefik  │
                                          │  Ingress  │
                                          └───────────┘

步骤1：部署到Kubernetes

# Clone the repo on your K8s host
cd vergeos-mcp-server

# Edit credentials in deploy.sh or create ~/.vergeos-credentials
cat > ~/.vergeos-credentials 

步骤3：测试服务器

# Health check
curl https://vergeos-mcp.yourdomain.com/health

# List VMs
curl https://vergeos-mcp.yourdomain.com/vms

# MCP protocol test
curl -X POST https://vergeos-mcp.yourdomain.com/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

步骤4：安装本地代理（在笔记本电脑上）

由于Windsurf仅支持基于stdio的MCP服务器，因此您需要一个本地代理：

# Create directory
mkdir -p ~/.mcp/vergeos
cd ~/.mcp/vergeos

# Create package.json
cat > package.json  index.js  ({ tools: TOOLS }));
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  try {
    const result = await apiCall(`/tools/${name}`, { method: "POST", body: JSON.stringify(args || {}) });
    return { content: [{ type: "text", text: JSON.stringify(result.result, null, 2) }] };
  } catch (error) {
    return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);
EOF

# Install dependencies
npm install

步骤5：配置Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "vergeos": {
      "command": "node",
      "args": ["/Users/yourusername/.mcp/vergeos/index.js"],
      "env": {
        "VERGEOS_MCP_URL": "https://vergeos-mcp.yourdomain.com"
      }
    }
  }
}

重新启动Windsurf以加载新的MCP服务器。

______________________________________________________________________

REST API参考

HTTP服务器还公开了一个用于直接访问的REST API：

MCP协议端点

______________________________________________________________________

交互示例

连接后，您可以询问您的AI助手：

• “列出VergeOS中的所有虚拟机”
• “关闭名为'test-VM'的VM的电源”
• “显示群集状态”
• “哪些警报处于活动状态？”
• “列出所有虚拟网络”
• “获取VM ID 34的详细信息”
• “群集中有多少个节点？”
• “显示最近20个日志条目”
• “创建名为“升级前”的VM 34快照”
• “列出web服务器VM的所有快照”
• “从快照ID 123还原VM 34”
• “向数据库VM添加2GB RAM”
• “向VM 34添加50GB数据磁盘”

______________________________________________________________________

VergeOS API说明

认证

VergeOS使用基于cookie的身份验证：

1. 张贴到 /api/sys/tokens 使用基本身份验证
2. 响应中包含令牌 $key 领域
3. 使用令牌作为cookie： Cookie: token=

# Get token
TOKEN=$(curl -sk -X POST "https://vergeos/api/sys/tokens" \
  -u "admin:password" \
  -H "Content-Type: application/json" \
  -d '{"login":"admin","password":"password"}' | jq -r '."$key"')

# Use token
curl -sk "https://vergeos/api/v4/vms" -b "token=$TOKEN"

API测验

• VM具有 is_snapshot: true 是模板，不运行虚拟机
• /machine_nics?machine= 可以从其他机器返回NIC；始终按机器ID筛选
• 使用 fields=most 获取详细的响应，但要注意较大的有效载荷

______________________________________________________________________

安全考虑

• 自签名证书的SSL验证已禁用（在家庭实验室中很常见）
• 将凭据存储在环境变量或Kubernetes secrets中
• 尽可能使用API令牌而不是用户名/密码
• HTTP服务器应位于TLS之后（由Traefik/Ingress处理）
• 考虑网络策略以限制对MCP服务器的访问

______________________________________________________________________

故障排除

连接问题

# Test VergeOS API directly
curl -sk https://your-vergeos-host/api/v4/vms -b "token=YOUR_TOKEN"

# Test MCP server
curl https://vergeos-mcp.yourdomain.com/health

令牌到期

令牌可能会过期。如果已配置，服务器将使用用户名/密码自动获取新令牌。

# Manually refresh token
curl -sk -X POST "https://your-vergeos-host/api/sys/tokens" \
  -u "admin:password" \
  -H "Content-Type: application/json" \
  -d '{"login":"admin","password":"password"}'

Kubernetes日志

kubectl logs -n vergeos-mcp deployment/vergeos-mcp
kubectl get pods -n vergeos-mcp

本地代理问题

# Test proxy directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node ~/.mcp/vergeos/index.js

______________________________________________________________________

文件结构

vergeos-mcp-server/
├── src/
│   ├── index.js           # Stdio MCP server (local use)
│   ├── http-server.js     # HTTP server (legacy)
│   ├── mcp-http-server.js # HTTP+MCP server (K8s deployment)
│   └── stdio-proxy.js     # Stdio proxy for remote server
├── local-proxy/
│   ├── package.json       # Local proxy dependencies
│   └── index.js           # Local proxy for Windsurf
├── deploy.sh              # Kubernetes deployment script
├── k8s-deployment.yaml    # Kubernetes manifests
├── package.json
├── .env.example
└── README.md

______________________________________________________________________

许可证

麻省理工学院