veeam-hybrid-mcp

mritsurgeon/veeam-hybrid-mcp

3.2

If you are the rightful owner of veeam-hybrid-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Veeam VBR MCP Server - Hybrid Edition is a versatile server that supports both traditional MCP and HTTP/OpenAPI modes, allowing seamless integration with various clients.

Tools
8
Resources
0
Prompts
0

Veeam VBR MCP Server - Hybrid Edition

A hybrid Model Context Protocol (MCP) server for Veeam Backup & Replication that supports both traditional MCP and HTTP/OpenAPI modes simultaneously.

๐Ÿš€ What Makes This "Hybrid"?

This server is NOT just a traditional MCP server. It's a hybrid architecture that:

  1. Runs both protocols simultaneously - MCP (stdio) AND HTTP (REST)
  2. Shares the same tool logic - Tools work identically in both modes
  3. Single deployment - One server serves both Claude Desktop AND Copilot Studio
  4. No external proxy needed - Unlike MCPO, this is built directly into the server

๐ŸŽฏ Three Operating Modes

Mode 1: Traditional MCP Only (Claude Desktop)

npm run start:mcp
# or
node vbr-mcp-server.js --mcp
  • Purpose: Claude Desktop and other MCP clients
  • Communication: Raw stdio protocol
  • Tools: Available as MCP tools (/backup-sessions, /backup-jobs)
  • Use Case: When you only need Claude Desktop integration

Mode 2: HTTP/OpenAPI Only (Copilot Studio)

npm run start:http
# or
node vbr-mcp-server.js --http --port=8000
  • Purpose: Copilot Studio, Open WebUI, web-based clients
  • Communication: HTTP/HTTPS REST endpoints
  • Tools: Available as REST API endpoints (/backup-sessions, /backup-jobs)
  • Use Case: When you only need web-based client integration

Mode 3: Hybrid (Both Modes Simultaneously) โญ RECOMMENDED

npm start
# or
node vbr-mcp-server.js
  • Purpose: Support both Claude Desktop AND Copilot Studio simultaneously
  • Communication: Both stdio AND HTTP protocols running at the same time
  • Tools: Available in both protocols simultaneously
  • Use Case: When you want both Claude Desktop AND Copilot Studio to work

๐Ÿ”‘ Key Benefits of Hybrid Mode

โœ… Single Server: One application serves both protocols
โœ… Shared Tools: Same tool logic for both MCP and HTTP
โœ… Consistent Behavior: Tools work identically in both modes
โœ… Easy Management: One configuration, one deployment
โœ… Flexible Clients: Support any MCP or HTTP client
โœ… No External Dependencies: Unlike MCPO, no proxy service needed

๐Ÿ› ๏ธ Installation

Prerequisites

  • Node.js 18+
  • npm or yarn
  • Access to Veeam Backup & Replication server

Local Installation

# Clone the repository
git clone https://github.com/mritsurgeon/veeam-hybrid-mcp.git
cd veeam-hybrid-mcp

# Install dependencies
npm install

# Copy and configure environment
cp env.example .env
# Edit .env with your Veeam server details

Docker Installation

# Build and run with docker-compose
docker-compose up -d

# Or build manually
docker build -t veeam-mcp-hybrid .
docker run -p 8000:8000 veeam-mcp-hybrid

โš™๏ธ Configuration

Environment Variables

Create a .env file:

VEEAM_HOST=your-veeam-server.com
VEEAM_PORT=9419
VEEAM_API_VERSION=1.2-rev0
VEEAM_USERNAME=your-username
VEEAM_PASSWORD=your-password
VEEAM_IGNORE_SSL=true

Configuration File

Edit config.json to customize server behavior:

{
  "modes": {
    "mcp": { "enabled": true },
    "http": { 
      "enabled": true, 
      "port": 8000,
      "authentication": { "enabled": false }
    }
  }
}

๐Ÿ”ง Available Tools

The server automatically loads these MCP tools:

Authentication

  • auth-tool: Authenticate with Veeam VBR server

Server Information

  • server-info-tool: Get Veeam server information

Backup Jobs โญ NEW - What you actually need!

  • backup-jobs-tool: Get configured backup jobs (not sessions!)
  • job-details-tool: Get detailed information about a specific backup job

Backup Infrastructure

  • backup-proxies-tool: Manage backup proxies
  • backup-repositories-tool: Manage backup repositories

Execution History

  • backup-sessions-tool: Monitor backup job execution sessions (history)
  • license-tools: Check license information

๐Ÿ”‘ Important: Jobs vs Sessions

Backup Jobs (What you usually want)

  • What they are: Configured backup jobs in VBR
  • Contains: Job settings, schedule, last run, next run, status
  • Use when: You want to see what backup jobs exist and their configuration
  • Tool: get-backup-jobs or backup-jobs-tool

Backup Sessions (Execution history)

  • What they are: Historical execution records of jobs
  • Contains: When jobs ran, results, errors, completion times
  • Use when: You want to see execution history and results
  • Tool: get-backup-sessions or backup-sessions-tool

๐ŸŒ HTTP/OpenAPI Mode

When running in HTTP mode, the server provides:

  • Root: GET / - Server information and available endpoints
  • Health: GET /health - Health check endpoint
  • OpenAPI Spec: GET /openapi.json - OpenAPI specification
  • Swagger UI: GET /docs - Interactive API documentation
  • Tool Endpoints: POST /{tool-name} - Execute specific tools

Example API Usage

# Get server health
curl http://localhost:8000/health

# Execute backup-jobs tool (get configured jobs)
curl -X POST http://localhost:8000/backup-jobs \
  -H "Content-Type: application/json" \
  -d '{"limit": 10, "typeFilter": "Backup"}'

# Execute backup-sessions tool (get execution history)
curl -X POST http://localhost:8000/backup-sessions \
  -H "Content-Type: application/json" \
  -d '{"limit": 10, "typeFilter": "BackupJob"}'

# Get OpenAPI specification
curl http://localhost:8000/openapi.json

๐Ÿ”Œ Integration with Copilot Studio

  1. Start the hybrid server:

    npm run start:http
    
  2. In Copilot Studio, add the tool URLs:

    • Base URL: http://your-server:8000
    • Individual tool URLs:
      • http://your-server:8000/auth - Authentication
      • http://your-server:8000/backup-jobs - Get backup jobs โญ
      • http://your-server:8000/job-details - Get job details โญ
      • http://your-server:8000/backup-sessions - Get execution history
      • http://your-server:8000/server-info - Server information
      • http://your-server:8000/backup-proxies - Backup proxies
      • http://your-server:8000/backup-repositories - Backup repositories
      • http://your-server:8000/license-tools - License information
  3. Authentication: First call the auth endpoint to authenticate with Veeam

๐Ÿ”Œ Integration with Claude Desktop

Prerequisites

  • Claude Desktop with Developer Mode enabled
  • Access to the server machine or ability to run the server locally

Configuration

  1. Find your Claude Desktop config file:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json
  2. Add the Veeam MCP server configuration:

Option A: Local Server (Recommended)
{
  "mcpServers": {
    "Veeam VBR": {
      "command": "node",
      "args": ["/full/path/to/vbr-mcp-server.js", "--mcp"]
    }
  }
}
Option B: Remote Server (Advanced)
{
  "mcpServers": {
    "Veeam VBR": {
      "command": "ssh",
      "args": ["user@server", "cd /path/to/server && node vbr-mcp-server.js --mcp"]
    }
  }
}
Option C: Docker Container
{
  "mcpServers": {
    "Veeam VBR": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "veeam-mcp-hybrid:latest", "node", "vbr-mcp-server.js", "--mcp"]
    }
  }
}

Important Notes for Claude Desktop

  • Use --mcp flag: This runs the server in MCP mode only (recommended for Claude Desktop)
  • Path must be absolute: Use full path to vbr-mcp-server.js
  • Alternative: Use no flags for hybrid mode (both MCP and HTTP simultaneously)
  • Restart Claude Desktop: After changing config, restart Claude Desktop
  • Check logs: If tools don't appear, check server logs for errors

Testing in Claude Desktop

  1. Restart Claude Desktop after configuration
  2. Look for "Veeam VBR" in the MCP servers list
  3. Try using tools like /backup-jobs or /backup-sessions
  4. If tools don't work, check server logs and Claude Desktop logs

๐Ÿงช Usage Examples

Get All Backup Jobs (Recommended for most use cases)

get-backup-jobs({
  "limit": 20,
  "typeFilter": "Backup"
})

Get Job Details with Recent Sessions

get-job-details({
  "jobId": "job-uuid-here",
  "includeSessions": true,
  "sessionLimit": 5
})

Get Recent Backup Sessions (Execution history)

get-backup-sessions({
  "limit": 10,
  "typeFilter": "BackupJob"
})

๐Ÿ”’ Security Considerations

  • Network Access: Ensure the server is only accessible from trusted networks
  • Authentication: Consider enabling API key authentication for production use
  • SSL/TLS: Use reverse proxy (nginx, traefik) for HTTPS in production
  • Firewall: Restrict access to port 8000 from external networks

๐Ÿณ Docker Deployment

Quick Start

# Start with docker-compose
docker-compose up -d

# Check logs
docker-compose logs -f

# Stop
docker-compose down

Production Deployment

# Build production image
docker build -t veeam-mcp-hybrid:latest .

# Run with environment variables
docker run -d \
  --name veeam-mcp \
  -p 8000:8000 \
  -e VEEAM_HOST=your-veeam-server.com \
  -e VEEAM_USERNAME=your-username \
  -e VEEAM_PASSWORD=your-password \
  veeam-mcp-hybrid:latest

๐Ÿ” Troubleshooting

Common Issues

  1. Connection Refused: Check if Veeam server is accessible and port 9419 is open
  2. Authentication Failed: Verify credentials in .env file
  3. SSL Errors: Set VEEAM_IGNORE_SSL=true for self-signed certificates
  4. Port Already in Use: Change port in config or stop conflicting service

Debug Mode

# Enable debug logging
DEBUG=* node vbr-mcp-server.js --http

# Check server logs
docker-compose logs -f veeam-mcp-server

Health Check

# Check server health
curl http://localhost:8000/health

# Expected response:
{
  "status": "healthy",
  "mode": "http",
  "tools": ["auth", "backup-jobs", "job-details", "backup-sessions", ...],
  "timestamp": "2024-01-01T00:00:00.000Z"
}

๐Ÿ“š API Documentation

Once the server is running, visit:

  • Swagger UI: http://localhost:8000/docs
  • OpenAPI Spec: http://localhost:8000/openapi.json

๐Ÿค Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

๐Ÿ“„ License

This project is licensed under the MIT License - see the file for details.

๐Ÿ™ Acknowledgments