VergeOS MCP Server

A Model Context Protocol (MCP) server for interacting with VergeOS virtualization platform. This enables AI assistants like Claude, Windsurf/Cascade, and other MCP-compatible clients to manage VMs, networks, tenants, and monitor your VergeOS cluster through natural language.

Architecture Overview

This project provides two deployment options:

┌─────────────────────────────────────────────────────────────────────────────┐
│                           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    │  │
│                                                              └──────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

When to Use Each Option

Option	Use Case
Local (stdio)	AI client runs on the same machine that can reach VergeOS
Remote (HTTP)	AI client is remote (e.g., laptop) and VergeOS is on a private network

Features

MCP Tools

VM Power Control

Tool	Description
list_vms	List all virtual machines (filter by running/name)
get_vm	Get detailed VM information by ID
get_vm_status	Get VM running status and power state
power_on_vm	Power on a VM
power_off_vm	Gracefully power off with optional wait and auto-force
force_off_vm	Force power off (hard shutdown)
reset_vm	Reset/reboot a VM

VM Configuration

Tool	Description
modify_vm	Change CPU cores and/or RAM (handles running VMs)
add_drive	Add a new disk drive to a VM
resize_drive	Expand an existing disk (increase only)
get_vm_nics	Get VM network interfaces
get_vm_drives	Get VM disk drives with sizes

Network Management

Tool	Description
list_networks	List all virtual networks
get_network	Get network details
network_action	Power on/off, reset, apply rules

Tenant Management

Tool	Description
list_tenants	List all tenants
get_tenant	Get tenant details
tenant_action	Power on/off, reset tenants

Cluster & Node Management

Tool	Description
list_nodes	List cluster nodes
get_node_stats	Get node statistics
get_cluster_status	Get cluster health status
get_cluster_stats	Get storage tier statistics

Storage & Monitoring

Tool	Description
list_volumes	List storage volumes
get_logs	Get system logs (filter by level/object type)
get_alarms	Get active alarms

Smart Features

• Graceful shutdown with wait: power_off_vm can wait for VM to shut down and auto-force if timeout expires
• Running VM handling: modify_vm detects running VMs and can auto-shutdown to apply CPU/RAM changes
• Log filtering: Filter logs by level (error, warning, audit) or object type (vm, node, vnet)

MCP Resources

• vergeos://cluster/status - Cluster status overview
• vergeos://vms/list - All virtual machines
• vergeos://networks/list - All virtual networks
• vergeos://alarms/active - Active system alarms

---

Option 1: Local Installation (stdio)

Use this if your AI client runs on a machine that can directly reach your VergeOS instance.

Installation

git clone <repo-url> vergeos-mcp-server
cd vergeos-mcp-server
npm install

Configuration

Create a .env file:

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

Or use an API token (recommended):

# 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 Desktop Configuration

Add to ~/.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"
      }
    }
  }
}

Windsurf Configuration

Add to ~/.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"
      }
    }
  }
}

---

Option 2: Remote Installation (Kubernetes + Local Proxy)

Use this if your AI client (e.g., Windsurf on your laptop) cannot directly reach VergeOS, but you have a Kubernetes cluster that can.

Architecture

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

Step 1: Deploy to Kubernetes

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

# Edit credentials in deploy.sh or create ~/.vergeos-credentials
cat > ~/.vergeos-credentials << EOF
VERGEOS_USER=admin
VERGEOS_PASS=your-password
EOF

# Deploy
./deploy.sh

This creates:

• Namespace: vergeos-mcp
• Deployment running the HTTP MCP server
• Service exposing port 3002
• IngressRoute for external access (Traefik)

Step 2: Configure DNS

Add a DNS record pointing to your Traefik ingress:

vergeos-mcp.yourdomain.com → <traefik-ip>

Step 3: Test the Server

# 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"}'

Step 4: Install Local Proxy (on your laptop)

Since Windsurf only supports stdio-based MCP servers, you need a local proxy:

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

# Create package.json
cat > package.json << 'EOF'
{
  "name": "vergeos-mcp-proxy",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.5.0",
    "node-fetch": "^3.3.2"
  }
}
EOF

# Create index.js
cat > index.js << 'EOF'
#!/usr/bin/env node
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

const SERVER_URL = process.env.VERGEOS_MCP_URL || "https://vergeos-mcp.yourdomain.com";

async function apiCall(path, options = {}) {
  const fetch = (await import("node-fetch")).default;
  const response = await fetch(`${SERVER_URL}${path}`, {
    ...options,
    headers: { "Content-Type": "application/json", ...options.headers },
  });
  if (!response.ok) throw new Error(`API Error: ${response.status}`);
  return response.json();
}

const server = new Server({ name: "vergeos", version: "1.0.0" }, { capabilities: { tools: {} } });

const TOOLS = [
  { name: "list_vms", description: "List all VMs in VergeOS", inputSchema: { type: "object", properties: {} } },
  { name: "get_vm", description: "Get VM details by ID", inputSchema: { type: "object", properties: { id: { type: "number" } }, required: ["id"] } },
  { name: "power_on_vm", description: "Power on a VM", inputSchema: { type: "object", properties: { id: { type: "number" } }, required: ["id"] } },
  { name: "power_off_vm", description: "Power off a VM", inputSchema: { type: "object", properties: { id: { type: "number" } }, required: ["id"] } },
  { name: "reset_vm", description: "Reset a VM", inputSchema: { type: "object", properties: { id: { type: "number" } }, required: ["id"] } },
  { name: "list_networks", description: "List virtual networks", inputSchema: { type: "object", properties: {} } },
  { name: "list_tenants", description: "List tenants", inputSchema: { type: "object", properties: {} } },
  { name: "list_nodes", description: "List cluster nodes", inputSchema: { type: "object", properties: {} } },
  { name: "get_cluster_status", description: "Get cluster status", inputSchema: { type: "object", properties: {} } },
  { name: "get_alarms", description: "Get active alarms", inputSchema: { type: "object", properties: {} } },
  { name: "get_logs", description: "Get system logs", inputSchema: { type: "object", properties: { limit: { type: "number" } } } },
];

server.setRequestHandler(ListToolsRequestSchema, async () => ({ 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

Step 5: Configure Windsurf

Add to ~/.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"
      }
    }
  }
}

Restart Windsurf to load the new MCP server.

---

REST API Reference

The HTTP server also exposes a REST API for direct access:

Endpoint	Method	Description
/health	GET	Health check
/tools	GET	List available MCP tools
/tools/:name	POST	Execute an MCP tool
/vms	GET	List all VMs
/vms/:id	GET	Get VM details
/vms/:id/:action	POST	VM action (poweron/poweroff/reset)
/networks	GET	List networks
/tenants	GET	List tenants
/nodes	GET	List nodes
/cluster/status	GET	Cluster status
/alarms	GET	Active alarms
/logs	GET	System logs

MCP Protocol Endpoints

Endpoint	Method	Description
/sse	GET	Server-Sent Events connection
/message	POST	MCP JSON-RPC messages

---

Example Interactions

Once connected, you can ask your AI assistant:

• "List all VMs in VergeOS"
• "Power off the VM named 'test-vm'"
• "Show me the cluster status"
• "What alarms are active?"
• "List all virtual networks"
• "Get details for VM ID 34"
• "How many nodes are in the cluster?"
• "Show me the last 20 log entries"

---

VergeOS API Notes

Authentication

VergeOS uses cookie-based authentication:

1. POST to /api/sys/tokens with Basic Auth
2. Response contains token in $key field
3. Use token as cookie: Cookie: token=<value>

# 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 Quirks

• VMs with is_snapshot: true are templates, not running VMs
• /machine_nics?machine=<ID> may return NICs from other machines; always filter by machine ID
• Use fields=most for detailed responses, but be aware of large payloads

---

Security Considerations

• SSL verification is disabled for self-signed certificates (common in homelabs)
• Store credentials in environment variables or Kubernetes secrets
• Use API tokens instead of username/password when possible
• The HTTP server should be behind TLS (handled by Traefik/Ingress)
• Consider network policies to restrict access to the MCP server

---

Troubleshooting

Connection Issues

# 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

Token Expiration

Tokens may expire. The server automatically fetches new tokens using username/password if configured.

# 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 Logs

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

Local Proxy Issues

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

---

File Structure

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

---

License

MIT