XenServer MCP Server

A Model Context Protocol (MCP) server for XenServer/XCP-ng administration. This server enables AI assistants to interact with XenServer infrastructure through natural language.

Features

Multi-cluster support: Manage multiple XenServer clusters from a single server
Comprehensive VM management: List, control, snapshot, and monitor virtual machines
Host management: Monitor and manage XenServer hosts
Storage operations: List and manage storage repositories and virtual disks
Network management: View and manage network configurations
Pool management: Get pool information and statistics
Template management: List and work with VM templates

Installation

Using Docker (Recommended)

# Pull from GitHub Container Registry
docker pull ghcr.io/acefei/xenserver-mcp:latest

# Or build locally
docker build -t xenserver-mcp .

Using uv/pip

# Install using uv
uv pip install -e .

# Or using pip
pip install -e .

Configuration

Create a configuration file at config/clusters.json in the project directory:

# Copy the example configuration
cp config/clusters.json.example config/clusters.json

# Edit with your credentials
nano config/clusters.json

Example configuration:

{
  "production": {
    "host": "xenserver1.example.com",
    "username": "root",
    "password": "your-secure-password"
  },
  "development": {
    "host": "xenserver2.example.com",
    "username": "root",
    "password": "another-password"
  }
}

Security Note: Ensure this file has restricted permissions and is not committed to version control:

chmod 600 config/clusters.json

Usage

Running with Docker

# Run the Docker container
docker run -i --rm \
  -v $(pwd)/config:/app/config:ro \
  ghcr.io/acefei/xenserver-mcp:latest

Running Locally

# Run with default configuration
xenserver-mcp

# Or run directly
python -m xenserver_mcp.server

# Set default cluster via environment variable
XENSERVER_CLUSTER=production xenserver-mcp

Using with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Using Docker:

{
  "mcpServers": {
    "xenserver": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/config:/app/config:ro",
        "ghcr.io/acefei/xenserver-mcp:latest"
      ]
    }
  }
}

Using Local Installation:

{
  "mcpServers": {
    "xenserver": {
      "command": "xenserver-mcp",
      "env": {
        "XENSERVER_CLUSTER": "production"
      }
    }
  }
}

Available Tools

Cluster Management

list_clusters - List all configured XenServer clusters
connect_cluster - Connect to a specific cluster
get_current_cluster - Show current cluster connection

Virtual Machine Management

list_vms - List all VMs (with filters for templates/snapshots)
get_vm_info - Get detailed VM information
vm_power_control - Control VM power state (start, shutdown, reboot, suspend, resume)
create_vm_snapshot - Create VM snapshots

Host Management

list_hosts - List all hosts in the pool
get_host_info - Get detailed host information

Storage Management

list_storage_repositories - List all storage repositories
list_virtual_disks - List virtual disk images

Network Management

list_networks - List all networks in the pool

Pool Management

get_pool_info - Get resource pool information and statistics

Template Management

list_templates - List all VM templates

Example Interactions

Connecting and Getting Started

User: Connect to the production cluster
Assistant: [Calls connect_cluster with cluster_id="production"]
Successfully connected to cluster: production (xenserver1.example.com)

User: Show me all running VMs
Assistant: [Calls list_vms]
Found 5 virtual machines:
- web-server-01 (UUID: xxx-xxx-xxx)
  Power State: Running
  vCPUs: 4, Memory: 8.00 GB
...

VM Operations

User: Get detailed info about web-server-01
Assistant: [Calls get_vm_info with vm_identifier="web-server-01"]
VM Information: web-server-01
UUID: xxx-xxx-xxx
Power State: Running
...

User: Create a snapshot of web-server-01 before the upgrade
Assistant: [Calls create_vm_snapshot]
Created snapshot 'pre-upgrade-snapshot' for VM 'web-server-01'
Snapshot UUID: yyy-yyy-yyy

User: Reboot the VM
Assistant: [Calls vm_power_control with action="reboot"]
Initiated clean reboot of VM: web-server-01

Infrastructure Monitoring

User: Show me the storage situation
Assistant: [Calls list_storage_repositories]
Found 2 storage repository(ies):
- Local Storage (UUID: aaa-aaa-aaa)
  Type: lvm
  Size: 1000.00 GB
  Used: 650.00 GB (65.0%)
  Free: 350.00 GB
...

User: What's the pool status?
Assistant: [Calls get_pool_info]
Pool Information: Production Pool
Total Hosts: 3
Total VMs: 25
Running VMs: 20
HA Enabled: True

Architecture

The server follows best practices from production MCP implementations:

Connection Management

Persistent connections with automatic reconnection
Session validation before each operation
Clean shutdown and resource cleanup

Error Handling

Graceful degradation on connection failures
Detailed error messages with context
Automatic session invalidation on errors

Logging

Comprehensive logging for debugging
Separate info/error log levels
Operation tracking for audit trails

Tool Design

Single-purpose, focused tools
Consistent parameter naming
Structured output formatting
Clear error messages

Development

Project Structure

xsmcp/
├── config/
│   ├── clusters.json.example  # Example cluster configuration
│   └── clusters.json          # Your actual config (gitignored)
├── src/
│   ├── xenserver_mcp/
│   │   ├── __init__.py
│   │   └── server.py
│   └── xen_api/              # XenAPI object-oriented middleware
├── docs/
│   ├── configuration.md
│   └── quickstart.md
├── examples/
│   └── basic_usage.py
├── pyproject.toml
└── README.md

Running Tests

# Install dev dependencies
uv pip install -e ".[dev]"

# Run linting
ruff check src/

# Format code
ruff format src/

Troubleshooting

Connection Issues

If you see "Not connected to any cluster":

Verify config/clusters.json exists and is valid JSON
Check cluster credentials are correct
Ensure XenServer host is reachable
Verify firewall allows HTTPS (443) connections

Session Timeout

The server automatically reconnects on session timeout. If persistent:

Check XenServer logs for authentication issues
Verify user account has appropriate permissions
Check for network instability

Permission Errors

Ensure the XenServer user has appropriate permissions:

Pool Admin role for full management
VM Admin role for VM operations only
Read-only role for monitoring

Security Considerations

Credential Storage: Configuration file contains plaintext passwords
- Use restricted file permissions (600)
- Never commit config/clusters.json to version control
- Consider using environment variables for CI/CD
- Keep config/ directory in .gitignore
Network Security: All communication is over HTTPS
- Verify SSL certificates in production
- Use VPN for remote access
Audit Logging: All operations are logged
- Review logs regularly
- Monitor for unexpected operations

Contributing

Contributions are welcome! Please:

Follow the existing code style (ruff formatting)
Add tests for new features
Update documentation
Submit pull requests

License

[Your chosen license]

Support

For issues and questions:

GitHub Issues: [Your repo URL]
Email: [email protected]

Acknowledgments

Based on best practices from:

blender-mcp - MCP server architecture patterns
XenAPI - XenServer API documentation
Model Context Protocol - MCP specification

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github		.github
config		config
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

acefei/xenserver-mcp

Folders and files

Latest commit

History

Repository files navigation