mritsurgeon/veeam-hybrid-mcp
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.
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:
- Runs both protocols simultaneously - MCP (stdio) AND HTTP (REST)
- Shares the same tool logic - Tools work identically in both modes
- Single deployment - One server serves both Claude Desktop AND Copilot Studio
- 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
orbackup-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
orbackup-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
-
Start the hybrid server:
npm run start:http
-
In Copilot Studio, add the tool URLs:
- Base URL:
http://your-server:8000
- Individual tool URLs:
http://your-server:8000/auth
- Authenticationhttp://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 historyhttp://your-server:8000/server-info
- Server informationhttp://your-server:8000/backup-proxies
- Backup proxieshttp://your-server:8000/backup-repositories
- Backup repositorieshttp://your-server:8000/license-tools
- License information
- Base URL:
-
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
-
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
- macOS:
-
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
- Restart Claude Desktop after configuration
- Look for "Veeam VBR" in the MCP servers list
- Try using tools like
/backup-jobs
or/backup-sessions
- 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
- Connection Refused: Check if Veeam server is accessible and port 9419 is open
- Authentication Failed: Verify credentials in
.env
file - SSL Errors: Set
VEEAM_IGNORE_SSL=true
for self-signed certificates - 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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
๐ License
This project is licensed under the MIT License - see the file for details.
๐ Acknowledgments
- Model Context Protocol for the MCP specification
- Open WebUI for the MCPO proxy concept
- Veeam Software for the backup and replication platform