virtfusion-mcp/README.md

VirtFusion MCP Server

A Model Context Protocol (MCP) server that wraps the VirtFusion virtualization control panel API. This enables AI assistants like Claude to manage VirtFusion infrastructure through natural language.

Features

• 84 tools covering the entire VirtFusion Admin API
• Server lifecycle management (create, build, delete, suspend, unsuspend)
• Power control (boot, shutdown, restart, poweroff)
• Network management (IPv4, whitelist, firewall, traffic)
• User management with external relation ID support
• Self-service operations (credit, resource packs, hourly profiles)
• Infrastructure management (hypervisors, IP blocks, packages, DNS)
• Backup and media management
• SSH key management
• Automatic API endpoint drift detection

Prerequisites

• Node.js 22 or later
• VirtFusion panel with Admin API access
• An API token generated from your VirtFusion admin panel

Installation

From source

git clone https://git.ezscale.cloud/EZSCALE/virtfusion-mcp.git
cd virtfusion-mcp
npm install
npm run build

Configuration

The server requires two environment variables:

Variable	Description	Example
VIRTFUSION_API_URL	Base URL of your VirtFusion API	https://cp.example.com/api/v1
VIRTFUSION_API_TOKEN	Admin API bearer token	your-api-token-here

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "virtfusion": {
      "command": "node",
      "args": ["/path/to/virtfusion-mcp/dist/index.js"],
      "env": {
        "VIRTFUSION_API_URL": "https://cp.example.com/api/v1",
        "VIRTFUSION_API_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Code

claude mcp add virtfusion -- node /path/to/virtfusion-mcp/dist/index.js \
  -e VIRTFUSION_API_URL=https://cp.example.com/api/v1 \
  -e VIRTFUSION_API_TOKEN=your-api-token

VS Code / Cursor

Add to your .vscode/mcp.json:

{
  "servers": {
    "virtfusion": {
      "command": "node",
      "args": ["/path/to/virtfusion-mcp/dist/index.js"],
      "env": {
        "VIRTFUSION_API_URL": "https://cp.example.com/api/v1",
        "VIRTFUSION_API_TOKEN": "your-api-token"
      }
    }
  }
}

Tool Reference

General (1 tool)

Tool	Description
general_test_connection	Test the API connection to VirtFusion

Servers (18 tools)

Tool	Description
servers_list	List all servers with optional filtering
servers_create	Create a new server
servers_get	Retrieve details of a specific server
servers_delete	Delete a server
servers_build	Build/rebuild a server with an OS template
servers_list_templates	List OS templates available for a server
servers_modify_name	Change a server's display name
servers_modify_cpu	Modify CPU cores for a server
servers_modify_memory	Modify memory allocation for a server
servers_throttle_cpu	Throttle a server's CPU
servers_get_traffic	Retrieve traffic statistics
servers_suspend	Suspend a server
servers_unsuspend	Unsuspend a server
servers_reset_password	Reset a server's root/admin password
servers_enable_vnc	Enable or disable VNC
servers_get_vnc	Retrieve VNC connection details
servers_set_custom_xml	Set custom XML configuration
servers_change_owner	Change the owner of a server
servers_change_package	Change a server's package
servers_set_backup_plan	Set a server's backup plan
servers_list_by_user	List servers owned by a user

Servers — Power (4 tools)

Tool	Description
servers_power_boot	Boot a server
servers_power_shutdown	Gracefully shutdown a server
servers_power_restart	Restart a server
servers_power_poweroff	Force power off a server

Servers — Network (5 tools)

Tool	Description
servers_network_whitelist_add	Add an IP to a server's network whitelist
servers_network_whitelist_remove	Remove an IP from a server's whitelist
servers_network_ipv4_add	Add specific IPv4 addresses
servers_network_ipv4_remove	Remove IPv4 addresses
servers_network_ipv4_add_qty	Add a quantity of IPv4 addresses

Servers — Firewall (4 tools)

Tool	Description
servers_firewall_get	Retrieve firewall configuration
servers_firewall_enable	Enable the firewall
servers_firewall_disable	Disable the firewall
servers_firewall_set_rules	Apply firewall rulesets

Servers — Traffic (4 tools)

Tool	Description
servers_traffic_list_blocks	List traffic blocks
servers_traffic_add_block	Add a traffic block
servers_traffic_remove_block	Remove a traffic block
servers_traffic_modify	Modify primary traffic allowance

Hypervisors (2 tools)

Tool	Description
hypervisors_list	List all hypervisors
hypervisors_get	Retrieve hypervisor details

Hypervisor Groups (3 tools)

Tool	Description
hypervisor_groups_list	List all hypervisor groups
hypervisor_groups_get	Retrieve group details
hypervisor_groups_get_resources	Retrieve group resources

IP Blocks (3 tools)

Tool	Description
ip_blocks_list	List all IP blocks
ip_blocks_get	Retrieve IP block details
ip_blocks_add_ipv4_range	Add an IPv4 range to a block

Packages (2 tools)

Tool	Description
packages_list	List all packages
packages_get	Retrieve package details

Queue (1 tool)

Tool	Description
queue_get	Retrieve queue item status

Backups (1 tool)

Tool	Description
backups_list_by_server	List backups for a server

DNS (1 tool)

Tool	Description
dns_get_service	Retrieve a DNS service

Media (2 tools)

Tool	Description
media_get_iso	Retrieve ISO image details
media_get_templates_by_package	List OS templates for a package

SSH Keys (4 tools)

Tool	Description
ssh_keys_create	Add an SSH key to a user
ssh_keys_get	Retrieve SSH key details
ssh_keys_delete	Delete an SSH key
ssh_keys_list_by_user	List SSH keys for a user

Users (7 tools)

Tool	Description
users_create	Create a new user
users_get	Retrieve a user by external relation ID
users_modify	Modify a user
users_delete	Delete a user
users_reset_password	Reset a user's password
users_generate_auth_tokens	Generate login tokens
users_generate_server_auth_tokens	Generate server-scoped login tokens

Self Service (19 tools)

Tool	Description
self_service_add_credit	Add credit to a user
self_service_cancel_credit	Cancel applied credit
self_service_get_currencies	Retrieve available currencies
self_service_add_hourly_group_profile	Add hourly group profile to user
self_service_remove_hourly_group_profile	Remove hourly group profile
self_service_add_resource_group_profile	Add resource group profile
self_service_remove_resource_group_profile	Remove resource group profile
self_service_add_resource_pack	Add resource pack to user
self_service_get_resource_pack	Retrieve a resource pack
self_service_modify_resource_pack	Modify a resource pack
self_service_delete_resource_pack	Delete a resource pack
self_service_get_hourly_stats	Retrieve hourly statistics
self_service_set_hourly_resource_pack	Set hourly resource pack
self_service_modify_access	Modify self-service access
self_service_get_report	Generate a user report
self_service_get_usage	Retrieve user usage data
self_service_delete_pack_servers	Delete all servers in a pack
self_service_suspend_pack_servers	Suspend all servers in a pack
self_service_unsuspend_pack_servers	Unsuspend all servers in a pack

Development

Build

npm run build

Run in development mode

VIRTFUSION_API_URL=https://cp.example.com/api/v1 \
VIRTFUSION_API_TOKEN=your-token \
npm run dev

API Endpoint Sync

This project includes tooling to detect when VirtFusion adds new API endpoints:

# Extract endpoints from the current OpenAPI spec
npm run extract-endpoints > endpoint-manifest.json

# Check for drift between spec and manifest
npm run check-endpoint-drift

The endpoint-sync workflow runs weekly and on any changes to openapi.yaml, creating an issue if drift is detected.

Adding new tools when VirtFusion updates their API

1. Download the updated openapi.yaml from VirtFusion docs
2. Run npm run check-endpoint-drift to see what changed
3. Implement new tools in the appropriate src/tools/*.ts module
4. Update the manifest: npm run extract-endpoints > endpoint-manifest.json
5. Commit everything together

License

MIT — see LICENSE