ProxmoxMCP-Plus

Servidor MCP de gerenciamento do Proxmox VE com integração completa OpenAPI para controle de VMs, containers e recursos de cluster.

GitHub

Documentação

ProxmoxMCP-Plus

Um servidor aprimorado do Model Context Protocol (MCP) baseado em Python para interagir com plataformas de virtualização Proxmox. Este projeto estende canvrno/ProxmoxMCP com recursos adicionais, incluindo integração completa com OpenAPI e capacidades expandidas de gerenciamento de virtualização.

Agradecimentos

Este projeto é construído sobre o projeto de código aberto ProxmoxMCP por @canvrno.

Novos Recursos e Melhorias

Principais Aprimoramentos

Categoria de Recurso	Descrição	Ferramentas
Gerenciamento do Ciclo de Vida de VMs	Criação, gerenciamento e exclusão completos de máquinas virtuais	`create_vm`, `delete_vm`
Gerenciamento de Energia	Controle os estados de energia das VMs	`start_vm`, `stop_vm`, `shutdown_vm`, `reset_vm`
Suporte a Contêineres	Gerenciamento completo do ciclo de vida de contêineres LXC	`get_containers`, `create_container`, `delete_container`, `start_container`, `stop_container`, `restart_container`, `update_container_resources`
Gerenciamento de Snapshots	Crie e gerencie snapshots de VMs/contêineres	`list_snapshots`, `create_snapshot`, `delete_snapshot`, `rollback_snapshot`
Backup e Restauração	Backup e restauração de VMs e contêineres	`list_backups`, `create_backup`, `restore_backup`, `delete_backup`
Gerenciamento de ISOs e Templates	Gerencie mídias de instalação e templates	`list_isos`, `list_templates`, `download_iso`, `delete_iso`
Monitoramento	Monitoramento de cluster e recursos	`get_nodes`, `get_node_status`, `get_vms`, `get_storage`, `get_cluster_status`
Integração OpenAPI	Endpoints REST API para integração externa	20+ endpoints de API
Segurança e Estabilidade	Tratamento de erros e validação de nível de produção	Autenticação baseada em token, registro abrangente

Construído Com

Proxmoxer - Wrapper Python para a API do Proxmox
MCP SDK - SDK do Model Context Protocol
Pydantic - Validação de dados usando anotações de tipo Python

Recursos

Integração completa com Cline e Open WebUI
Construído com o SDK MCP oficial
Autenticação segura baseada em token com Proxmox
Gerenciamento completo do ciclo de vida de VMs (criar, iniciar, parar, reiniciar, desligar, excluir)
Execução de comandos no console da VM
Suporte ao gerenciamento de contêineres LXC
Detecção inteligente de tipo de armazenamento (LVM/baseado em arquivo)
Sistema de registro configurável
Implementação type-safe com Pydantic
Formatação de saída rica com temas personalizáveis
Endpoints REST OpenAPI para integração
20+ endpoints de API totalmente funcionais
Gerenciamento completo de snapshots (criar, excluir, reverter)
Capacidades de backup e restauração
Gerenciamento de ISOs e templates

Instalação

Pré-requisitos

Gerenciador de pacotes UV (recomendado)
Python 3.9 ou superior
Git
Acesso a um servidor Proxmox com credenciais de token API

Antes de começar, certifique-se de ter:

Hostname ou IP do servidor Proxmox
Token API do Proxmox (veja Configuração do Token API)
UV instalado (pip install uv)

Opção 1: Instalação Rápida (Recomendada)

Clone e configure o ambiente:

# Clone repository
git clone https://github.com/RekklesNA/ProxmoxMCP-Plus.git
cd ProxmoxMCP-Plus

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1  # Windows

Instale as dependências:

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

Crie a configuração:

# Create config directory and copy template
mkdir -p proxmox-config
cp proxmox-config/config.example.json proxmox-config/config.json

Edite proxmox-config/config.json:

{
    "proxmox": {
        "host": "PROXMOX_HOST",        # Required: Your Proxmox server address
        "port": 8006,                  # Optional: Default is 8006
        "verify_ssl": false,           # Optional: Set false for self-signed certs
        "service": "PVE"               # Optional: Default is PVE
    },
    "auth": {
        "user": "USER@pve",            # Required: Your Proxmox username
        "token_name": "TOKEN_NAME",    # Required: API token ID
        "token_value": "TOKEN_VALUE"   # Required: API token value
    },
    "logging": {
        "level": "INFO",               # Optional: DEBUG for more detail
        "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
        "file": "proxmox_mcp.log"      # Optional: Log to file
    },
    "mcp": {
        "host": "127.0.0.1",           # Optional: Host for SSE/STREAMABLE transports
        "port": 8000,                  # Optional: Port for SSE/STREAMABLE transports
        "transport": "STDIO"           # Optional: STDIO, SSE, or STREAMABLE
    }
}

Verificando a Instalação

Verifique o ambiente Python:

python -c "import proxmox_mcp; print('Installation OK')"

Execute os testes:
```
pytest
```

Verifique a configuração:

# Linux/macOS
PROXMOX_MCP_CONFIG="proxmox-config/config.json" python -m proxmox_mcp.server

# Windows (PowerShell)
$env:PROXMOX_MCP_CONFIG="proxmox-config\config.json"; python -m proxmox_mcp.server

Configuração

Configuração do Token API do Proxmox

Faça login na interface web do Proxmox
Navegue até Datacenter -> Permissions -> API Tokens
Crie um novo token API:
- Selecione um usuário (ex.: root@pam)
- Insira um ID de token (ex.: "mcp-token")
- Desmarque "Privilege Separation" se quiser acesso total
- Salve e copie o ID do token e o segredo

Executando o Servidor

Modo de Desenvolvimento

Para testes e desenvolvimento:

# Activate virtual environment first
source .venv/bin/activate  # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1  # Windows

# Run the server
python -m proxmox_mcp.server

Configuração de Transporte MCP

O servidor MCP suporta vários modos de transporte. Configure-os na seção mcp do seu proxmox-config/config.json:

STDIO: Padrão. Execute via stdio para clientes MCP como Claude Desktop/Cline.
SSE: Sirva MCP via Server-Sent Events (SSE).
STREAMABLE: Sirva MCP via HTTP com streaming.

Implantação OpenAPI (Pronta para Produção)

Implante o ProxmoxMCP Plus como endpoints REST OpenAPI padrão para integração com Open WebUI e outros aplicativos.

Início Rápido do OpenAPI

# Install mcpo (MCP-to-OpenAPI proxy)
pip install mcpo

# Start OpenAPI service on port 8811
./start_openapi.sh

Implantação com Docker

# Build and run with Docker
docker build -t proxmox-mcp-api .
docker run -d --name proxmox-mcp-api -p 8811:8811 \
  -v $(pwd)/proxmox-config:/app/proxmox-config proxmox-mcp-api

# Or use Docker Compose
docker-compose up -d

Acessar o Serviço OpenAPI

Após a implantação, acesse seu serviço em:

Documentação da API: http://your-server:8811/docs
Especificação OpenAPI: http://your-server:8811/openapi.json
Verificação de Saúde: http://your-server:8811/health

Integração com Claude Desktop

Para usuários do Claude Desktop, adicione esta configuração ao seu arquivo de configurações MCP:

Localização do arquivo de configuração:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Configuração Rápida:

Copie a configuração de exemplo:

# macOS
cp proxmox-config/claude_desktop_config.example.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
cp proxmox-config/claude_desktop_config.example.json ~/.config/Claude/claude_desktop_config.json

# Windows (PowerShell)
Copy-Item proxmox-config\claude_desktop_config.example.json $env:APPDATA\Claude\claude_desktop_config.json

Edite o arquivo e substitua os seguintes valores:
- /absolute/path/to/ProxmoxMCP-Plus - Caminho completo para sua instalação
- your-proxmox-host - IP ou hostname do seu servidor Proxmox
- username@pve - Seu nome de usuário do Proxmox
- token-name - Nome do seu token API
- token-value - Valor do seu token API

Configuração:

{
    "mcpServers": {
        "ProxmoxMCP-Plus": {
            "command": "/absolute/path/to/ProxmoxMCP-Plus/.venv/bin/python",
            "args": ["-m", "proxmox_mcp.server"],
            "env": {
                "PYTHONPATH": "/absolute/path/to/ProxmoxMCP-Plus/src",
                "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP-Plus/proxmox-config/config.json",
                "PROXMOX_HOST": "your-proxmox-host",
                "PROXMOX_USER": "username@pve",
                "PROXMOX_TOKEN_NAME": "token-name",
                "PROXMOX_TOKEN_VALUE": "token-value",
                "PROXMOX_PORT": "8006",
                "PROXMOX_VERIFY_SSL": "false",
                "PROXMOX_SERVICE": "PVE",
                "LOG_LEVEL": "DEBUG"
            }
        }
    }
}

Após a configuração:

Reinicie o Claude Desktop
As ferramentas do ProxmoxMCP-Plus estarão disponíveis em suas conversas
Agora você pode gerenciar sua infraestrutura Proxmox através do Claude Desktop!

Integração com Cline Desktop

Para usuários do Cline, adicione esta configuração ao seu arquivo de configurações MCP (normalmente em ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
    "mcpServers": {
        "ProxmoxMCP-Plus": {
            "command": "/absolute/path/to/ProxmoxMCP-Plus/.venv/bin/python",
            "args": ["-m", "proxmox_mcp.server"],
            "cwd": "/absolute/path/to/ProxmoxMCP-Plus",
            "env": {
                "PYTHONPATH": "/absolute/path/to/ProxmoxMCP-Plus/src",
                "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP-Plus/proxmox-config/config.json",
                "PROXMOX_HOST": "your-proxmox-host",
                "PROXMOX_USER": "username@pve",
                "PROXMOX_TOKEN_NAME": "token-name",
                "PROXMOX_TOKEN_VALUE": "token-value",
                "PROXMOX_PORT": "8006",
                "PROXMOX_VERIFY_SSL": "false",
                "PROXMOX_SERVICE": "PVE",
                "LOG_LEVEL": "DEBUG"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}

Ferramentas Disponíveis e Endpoints de API

O servidor fornece ferramentas MCP abrangentes e endpoints REST API correspondentes:

Ferramentas de Gerenciamento de VMs

create_vm

Crie uma nova máquina virtual com os recursos especificados.

Parâmetros:

node (string, obrigatório): Nome do nó
vmid (string, obrigatório): ID da nova VM
name (string, obrigatório): Nome da VM
cpus (inteiro, obrigatório): Número de núcleos de CPU (1-32)
memory (inteiro, obrigatório): Memória em MB (512-131072)
disk_size (inteiro, obrigatório): Tamanho do disco em GB (5-1000)
storage (string, opcional): Nome do pool de armazenamento
ostype (string, opcional): Tipo de SO (padrão: l26)

Endpoint da API:

POST /create_vm
Content-Type: application/json

{
    "node": "pve",
    "vmid": "200",
    "name": "my-vm",
    "cpus": 1,
    "memory": 2048,
    "disk_size": 10
}

Exemplo de Resposta:

VM 200 created successfully.

VM Configuration:
  - Name: my-vm
  - Node: pve
  - VM ID: 200
  - CPU Cores: 1
  - Memory: 2048 MB (2.0 GB)
  - Disk: 10 GB (local-lvm, raw format)
  - Storage Type: lvmthin
  - Network: virtio (bridge=vmbr0)
  - QEMU Agent: Enabled

Task ID: UPID:pve:001AB729:0442E853:682FF380:qmcreate:200:root@pam!mcp

Gerenciamento de Energia de VMs

start_vm: Inicia uma máquina virtual

POST /start_vm
{"node": "pve", "vmid": "200"}

stop_vm: Força a parada de uma máquina virtual

POST /stop_vm
{"node": "pve", "vmid": "200"}

shutdown_vm: Desliga uma máquina virtual de forma graciosa

POST /shutdown_vm
{"node": "pve", "vmid": "200"}

reset_vm: Reinicia uma máquina virtual

POST /reset_vm
{"node": "pve", "vmid": "200"}

delete_vm: Exclui completamente uma máquina virtual

POST /delete_vm
{"node": "pve", "vmid": "200", "force": false}

Ferramentas de Gerenciamento de Snapshots

list_snapshots

Lista todos os snapshots de uma VM ou contêiner.

Parâmetros:

node (string, obrigatório): Nome do nó host (ex.: 'pve')
vmid (string, obrigatório): ID da VM ou contêiner (ex.: '100')
vm_type (string, opcional): Tipo - 'qemu' para VMs, 'lxc' para contêineres (padrão: 'qemu')

Endpoint da API: POST /list_snapshots

Exemplo:

POST /list_snapshots
{"node": "pve", "vmid": "100", "vm_type": "qemu"}

create_snapshot

Cria um snapshot de uma VM ou contêiner.

Parâmetros:

node (string, obrigatório): Nome do nó host
vmid (string, obrigatório): ID da VM ou contêiner
snapname (string, obrigatório): Nome do snapshot (sem espaços, ex.: 'before-update')
description (string, opcional): Descrição do snapshot
vmstate (booleano, opcional): Incluir estado da memória (somente VMs, padrão: false)
vm_type (string, opcional): Tipo - 'qemu' ou 'lxc' (padrão: 'qemu')

Endpoint da API:

POST /create_snapshot
Content-Type: application/json

{
    "node": "pve",
    "vmid": "100",
    "snapname": "pre-upgrade",
    "description": "Before system upgrade",
    "vmstate": true
}

delete_snapshot

Exclui um snapshot.

Parâmetros:

node (string, obrigatório): Nome do nó host
vmid (string, obrigatório): ID da VM ou contêiner
snapname (string, obrigatório): Nome do snapshot a ser excluído
vm_type (string, opcional): Tipo - 'qemu' ou 'lxc' (padrão: 'qemu')

Endpoint da API:

POST /delete_snapshot
{"node": "pve", "vmid": "100", "snapname": "old-snapshot"}

rollback_snapshot

Reverte VM/contêiner para um snapshot anterior.

AVISO: Isso interromperá a VM/contêiner e restaurará o estado do snapshot!

Parâmetros:

node (string, obrigatório): Nome do nó host
vmid (string, obrigatório): ID da VM ou contêiner
snapname (string, obrigatório): Nome do snapshot a ser restaurado
vm_type (string, opcional): Tipo - 'qemu' ou 'lxc' (padrão: 'qemu')

Endpoint da API:

POST /rollback_snapshot
{"node": "pve", "vmid": "100", "snapname": "before-update"}

Ferramentas de Gerenciamento de Contêineres

get_containers

Lista todos os contêineres LXC no cluster.

Endpoint da API: POST /get_containers

Exemplo de Resposta:

Containers

nginx-server (ID: 200)
  - Status: RUNNING
  - Node: pve
  - CPU Cores: 2
  - Memory: 1.5 GB / 2.0 GB (75.0%)

create_container

Cria um novo contêiner LXC com a configuração especificada.

Parâmetros:

node (string, obrigatório): Nome do nó host (ex.: 'pve')
vmid (string, obrigatório): Número do ID do contêiner (ex.: '200')
ostemplate (string, obrigatório): Caminho do template do SO (ex.: 'local:vztmpl/alpine-3.19-default_20240207_amd64.tar.xz')
hostname (string, opcional): Hostname do contêiner (padrão: 'ct-{vmid}')
cores (inteiro, opcional): Número de núcleos de CPU (padrão: 1)
memory (inteiro, opcional): Tamanho da memória em MiB (padrão: 512)
swap (inteiro, opcional): Tamanho do swap em MiB (padrão: 512)
disk_size (inteiro, opcional): Tamanho do disco raiz em GB (padrão: 8)
storage (string, opcional): Pool de armazenamento para rootfs (detecção automática se não especificado)
password (string, opcional): Senha do root
ssh_public_keys (string, opcional): Chaves públicas SSH para o usuário root
network_bridge (string, opcional): Nome da bridge de rede (padrão: 'vmbr0')
start_after_create (booleano, opcional): Iniciar contêiner após a criação (padrão: false)
unprivileged (booleano, opcional): Criar contêiner sem privilégios (padrão: true)

Endpoint da API:

POST /create_container
Content-Type: application/json

{
    "node": "pve",
    "vmid": "200",
    "ostemplate": "local:vztmpl/alpine-3.19-default_20240207_amd64.tar.xz",
    "hostname": "my-container",
    "cores": 2,
    "memory": 1024,
    "disk_size": 10
}

delete_container

Exclui/remove um contêiner LXC completamente.

AVISO: Esta operação exclui permanentemente o contêiner e todos os seus dados!

Parâmetros:

selector (string, obrigatório): Seletor de contêiner - '123' | 'pve1:123' | 'pve1/name' | 'name'
force (booleano, opcional): Forçar exclusão mesmo se o contêiner estiver em execução (padrão: false)

Endpoint da API:

POST /delete_container
Content-Type: application/json

{
    "selector": "200",
    "force": false
}

Ferramentas de Backup e Restauração

list_backups

Lista os backups disponíveis no cluster.

Parâmetros:

node (string, opcional): Filtrar por nó
storage (string, opcional): Filtrar por pool de armazenamento
vmid (string, opcional): Filtrar por ID de VM/contêiner

Endpoint da API: POST /list_backups

Exemplo:

POST /list_backups
{"node": "pve", "storage": "backup-storage"}

create_backup

Cria um backup de uma VM ou contêiner.

Parâmetros:

node (string, obrigatório): Nó onde a VM/contêiner é executado
vmid (string, obrigatório): ID da VM ou contêiner para backup
storage (string, obrigatório): Armazenamento de backup de destino
compress (string, opcional): Compressão - '0', 'gzip', 'lz4', 'zstd' (padrão: 'zstd')
mode (string, opcional): Modo de backup - 'snapshot', 'suspend', 'stop' (padrão: 'snapshot')
notes (string, opcional): Notas/descrição do backup

Endpoint da API:

POST /create_backup
Content-Type: application/json

{
    "node": "pve",
    "vmid": "100",
    "storage": "backup-storage",
    "compress": "zstd",
    "mode": "snapshot",
    "notes": "Weekly backup"
}

restore_backup

Restaura uma VM ou contêiner a partir de um backup.

Parâmetros:

node (string, obrigatório): Nó de destino para restauração
archive (string, obrigatório): ID do volume de backup (da saída do list_backups)
vmid (string, obrigatório): Novo ID de VM/contêiner para a máquina restaurada
storage (string, opcional): Armazenamento de destino para discos (usa o original se não especificado)
unique (booleano, opcional): Gerar endereços MAC únicos (padrão: true)

Endpoint da API:

POST /restore_backup
Content-Type: application/json

{
    "node": "pve",
    "archive": "backup:backup/vzdump-qemu-100-2024_01_15.vma.zst",
    "vmid": "200",
    "unique": true
}

delete_backup

Exclui um arquivo de backup do armazenamento.

AVISO: Isso exclui permanentemente o backup!

Parâmetros:

node (string, obrigatório): Nome do nó
storage (string, obrigatório): Nome do pool de armazenamento
volid (string, obrigatório): ID do volume de backup a ser excluído

Endpoint da API:

POST /delete_backup
{
    "node": "pve",
    "storage": "backup-storage",
    "volid": "backup:backup/vzdump-qemu-100-2024_01_15.vma.zst"
}

Ferramentas de Gerenciamento de ISO e Templates

list_isos

Lista as imagens ISO disponíveis no cluster.

Parâmetros:

node (string, opcional): Filtrar por nó
storage (string, opcional): Filtrar por pool de armazenamento

Endpoint da API: POST /list_isos

Retorna: Lista de ISOs com nome do arquivo, tamanho e localização do armazenamento.

list_templates

Lista os templates de SO disponíveis para criação de contêineres.

Parâmetros:

node (string, opcional): Filtrar por nó
storage (string, opcional): Filtrar por pool de armazenamento

Endpoint da API: POST /list_templates

Retorna: Lista de templates (vztmpl) com nome, tamanho e armazenamento. Use o ID de volume retornado com o parâmetro ostemplate do create_container.

download_iso

Baixa uma imagem ISO de uma URL para o armazenamento Proxmox.

Parâmetros:

node (string, obrigatório): Nome do nó de destino
storage (string, obrigatório): Pool de armazenamento de destino (deve suportar conteúdo ISO)
url (string, obrigatório): URL para download
filename (string, obrigatório): Nome do arquivo de destino (ex.: 'ubuntu-22.04-live-server-amd64.iso')
checksum (string, opcional): Checksum para verificação
checksum_algorithm (string, opcional): Algoritmo - 'sha256', 'sha512', 'md5' (padrão: 'sha256')

Endpoint da API:

POST /download_iso
Content-Type: application/json

{
    "node": "pve",
    "storage": "local",
    "url": "https://releases.ubuntu.com/22.04/ubuntu-22.04-live-server-amd64.iso",
    "filename": "ubuntu-22.04-live-server-amd64.iso",
    "checksum": "a1b2c3..."
}

delete_iso

Exclui um ISO ou template do armazenamento.

Parâmetros:

node (string, obrigatório): Nome do nó
storage (string, obrigatório): Nome do pool de armazenamento
filename (string, obrigatório): Nome do arquivo ISO/template a ser excluído

Endpoint da API:

POST /delete_iso
{
    "node": "pve",
    "storage": "local",
    "filename": "old-distro.iso"
}

Ferramentas de Monitoramento

get_nodes

Lista todos os nós no cluster Proxmox.

Endpoint da API: POST /get_nodes

Exemplo de Resposta:

Proxmox Nodes

pve-compute-01
  - Status: ONLINE
  - Uptime: 156d 12h
  - CPU Cores: 64
  - Memory: 186.5 GB / 512.0 GB (36.4%)

get_node_status

Obtém o status detalhado de um nó específico.

Parâmetros:

node (string, obrigatório): Nome do nó

Endpoint da API: POST /get_node_status

get_vms

Lista todas as VMs no cluster.

Endpoint da API: POST /get_vms

get_storage

Lista os pools de armazenamento disponíveis.

Endpoint da API: POST /get_storage

get_cluster_status

Obtém o status geral e a saúde do cluster.

Endpoint da API: POST /get_cluster_status

execute_vm_command

Executa um comando no console de uma VM usando o QEMU Guest Agent.

Parâmetros:

node (string, obrigatório): Nome do nó onde a VM está em execução
vmid (string, obrigatório): ID da VM
command (string, obrigatório): Comando a ser executado

Endpoint da API: POST /execute_vm_command

Requisitos:

A VM deve estar em execução
O QEMU Guest Agent deve estar instalado e em execução na VM

Integração com Open WebUI

Configurar Open WebUI

Acesse sua instância do Open WebUI
Navegue até Configurações → Conexões → OpenAPI
Adicione uma nova configuração de API:

{
  "name": "Proxmox MCP API Plus",
  "base_url": "http://your-server:8811",
  "api_key": "",
  "description": "Enhanced Proxmox Virtualization Management API"
}

Criação de VM em Linguagem Natural

O sistema suporta solicitações de criação de VM em linguagem natural por meio de assistentes de IA. Exemplos de solicitações:

"Você pode criar uma VM com 1 núcleo de CPU e 2 GB de RAM com 10 GB de disco de armazenamento"
"Crie uma nova VM para testes com recursos mínimos"
"Preciso de um servidor de desenvolvimento com 4 núcleos e 8 GB de RAM"

O assistente de IA chamará automaticamente as APIs apropriadas e fornecerá feedback detalhado.

Suporte a Tipos de Armazenamento

Detecção Inteligente de Armazenamento

ProxmoxMCP Plus detecta automaticamente os tipos de armazenamento e seleciona os formatos de disco apropriados:

Armazenamento LVM (local-lvm, vm-storage)

Formato: raw
Alto desempenho
Nota: Sem suporte a imagem cloud-init

Armazenamento Baseado em Arquivos (local, NFS, CIFS)

Formato: qcow2
Suporte a cloud-init
Capacidades flexíveis de snapshot

Estrutura do Projeto

ProxmoxMCP-Plus/
├── src/                          # Source code
│   └── proxmox_mcp/
│       ├── server.py             # Main MCP server implementation
│       ├── config/               # Configuration handling
│       ├── core/                 # Core functionality
│       ├── formatting/           # Output formatting and themes
│       ├── tools/                # Tool implementations
│       │   ├── vm.py             # VM management
│       │   ├── container.py      # Container management
│       │   └── console/          # VM console operations
│       └── utils/                # Utilities (auth, logging)
│
├── tests/                        # Unit test suite
├── test_scripts/                 # Integration tests & demos
│   ├── README.md                 # Test documentation
│   ├── test_vm_power.py          # VM power management tests
│   ├── test_vm_start.py          # VM startup tests
│   ├── test_create_vm.py         # VM creation tests
│   └── test_openapi.py           # OpenAPI service tests
│
├── proxmox-config/               # Configuration files
│   └── config.json               # Server configuration
│
├── Configuration Files
│   ├── pyproject.toml            # Project metadata
│   ├── docker-compose.yml        # Docker orchestration
│   ├── Dockerfile                # Docker image definition
│   └── requirements.in           # Dependencies
│
├── Scripts
│   ├── start_server.sh           # MCP server launcher
│   └── start_openapi.sh          # OpenAPI service launcher
│
└── Documentation
    ├── README.md                 # This file
    ├── VM_CREATION_GUIDE.md      # VM creation guide
    ├── OPENAPI_DEPLOYMENT.md     # OpenAPI deployment
    └── LICENSE                   # MIT License

Testes

Executar Testes Unitários

pytest

Executar Testes de Integração

cd test_scripts

# Test VM power management
python test_vm_power.py

# Test VM creation
python test_create_vm.py

# Test OpenAPI service
python test_openapi.py

Testes de API com curl

# Test node listing
curl -X POST "http://your-server:8811/get_nodes" \
  -H "Content-Type: application/json" \
  -d "{}"

# Test VM creation
curl -X POST "http://your-server:8811/create_vm" \
  -H "Content-Type: application/json" \
  -d '{
    "node": "pve",
    "vmid": "300",
    "name": "test-vm",
    "cpus": 1,
    "memory": 2048,
    "disk_size": 10
  }'

Segurança em Produção

Autenticação por Chave de API

Configure o acesso seguro à API:

export PROXMOX_API_KEY="your-secure-api-key"
export PROXMOX_MCP_CONFIG="/app/proxmox-config/config.json"

Proxy Reverso Nginx

Exemplo de configuração do nginx:

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:8811;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Solução de Problemas

Problemas Comuns

Porta já em uso

netstat -tlnp | grep 8811
# Change port if needed
mcpo --port 8812 -- ./start_server.sh

Erros de configuração

# Verify config file
cat proxmox-config/config.json

Problemas de conexão

# Test Proxmox connectivity
curl -k https://your-proxmox:8006/api2/json/version

Visualizar Logs

# View service logs
tail -f proxmox_mcp.log

# Docker logs
docker logs proxmox-mcp-api -f

Status de Implantação

Status de Conclusão de Recursos

Prontidão para Produção

ProxmoxMCP Plus está pronto para implantação em produção. O sistema suporta solicitações de criação de VM em linguagem natural por meio de assistentes de IA. Quando um usuário solicita a criação de uma VM (ex.: "crie uma VM com 1 núcleo de CPU e 2 GB de RAM com 10 GB de disco de armazenamento"), o sistema irá:

Chamar o endpoint da API create_vm
Selecionar automaticamente o armazenamento e formato apropriados
Criar VMs que atendam aos requisitos especificados
Retornar informações detalhadas de configuração
Fornecer recomendações de próximos passos

Desenvolvimento

Após ativar seu ambiente virtual:

Executar testes: pytest
Formatar código: black .
Verificação de tipos: mypy .
Lint: ruff .

Licença

Licença MIT

Agradecimentos Especiais

@canvrno pelo projeto fundamental ProxmoxMCP
Agradecimentos à comunidade Proxmox por fornecer a plataforma de virtualização poderosa
Agradecimentos a todos os contribuidores e usuários pelo suporte

ProxmoxMCP Plus com integração OpenAPI está pronto para implantação em produção.