使用说明
proxmox-mcp-go
A Proxmox MCP (Model Context Protocol) server written in Go. Exposes Proxmox VE management tools to AI agents over HTTP using the MCP streamable HTTP transport.
Getting Started
Prerequisites
- Go 1.24+
- Docker (optional)
Configuration
Copy and edit the config file:
bind_port: 3001
verbose: true
pve_url: "https://your-proxmox-host:8006"
pve_token_id: "root@pam!mcp"
pve_token: "your-api-token-secret"
# pve_verify_ssl: false
mcp_api_key: "your-secret-key-here"
# mcp_stdio: false
| Field | Description |
|---|---|
bind_host |
HTTP server bind address (default: 0.0.0.0) |
bind_port |
HTTP server port (default: 3001) |
pve_url |
Proxmox VE API URL |
pve_token_id |
API token ID (e.g. root@pam!mcp) |
pve_token |
API token secret |
pve_verify_ssl |
Verify the Proxmox TLS certificate (default: false, as Proxmox commonly uses self-signed certs) |
mcp_api_key |
API key for authenticating MCP endpoint requests (Bearer token) |
mcp_stdio |
Enable stdio transport (default: false) |
Running
go run main.go --config=$PWD/config/config.yaml
Docker
./run-docker.sh
# Or with custom config/port
CONFIG_FILE=/path/to/config.yaml PORT=3001 ./run-docker.sh
MCP Endpoint
The MCP server is available at POST /mcp using the streamable HTTP transport.
Connecting from Claude Code
{
"mcpServers": {
"proxmox": {
"type": "url",
"url": "http://your-host:3001/mcp",
"headers": {
"Authorization": "Bearer your-secret-key-here"
}
}
}
}
When mcp_api_key is set, all requests to /mcp must include a Authorization: Bearer <key> header. If the key is not set, the endpoint is unauthenticated.
Available Tools
| Category | Tools |
|---|---|
| Cluster | get_version, get_cluster_status, list_nodes, get_node_status, get_node_network |
| Guest | list_vms, list_containers, list_cluster_resources, get_guest_config, start_guest, stop_guest, get_next_id, update_guest_config, migrate_guest, resize_guest_disk |
| Create | create_vm, create_container, clone_guest, delete_guest, convert_to_template |
| Snapshot | list_snapshots, create_snapshot, rollback_snapshot, delete_snapshot |
| Backup | backup_guest, list_backups, restore_backup |
| Storage | list_storage, list_templates, list_isos, download_template |
| Task | list_tasks, get_task_status, get_task_log |
Destructive tools (delete_guest, rollback_snapshot, restore_backup) require an explicit confirm: "true" argument; without it they return an error and make no API call. Tool arguments used in Proxmox API paths (node, vmid, type, snapname, storage, ...) are validated against path traversal, and type/action values are checked against allowlists.
API
GET /api/v1/ # Default page
GET /api/v1/health # Health check
POST /mcp # MCP streamable HTTP endpoint
Project Structure
main.go # Entry point
app/ # Application lifecycle, logging, signal handling
server/ # HTTP server, routing, middleware
config/ # Configuration parsing
mcp/ # MCP server, Proxmox client, tool registrations
Development
# Build binary
go build -o ./tmp/main.exe .
# Run tests
go test ./...
# Lint
golangci-lint run --fix
# Update vendor after dependency changes
go mod tidy && go mod vendor
