ProxmoxMCP-Plus

ProxmoxMCP-Plus

Opere o Proxmox VE a partir de clientes MCP, agentes de IA e ferramentas OpenAPI através de um plano de controle consciente de segurança para VMs, LXCs, snapshots, backups, ISOs, comandos de contêiner e trabalhos persistentes de longa duração.

Início Rápido | Instalação do Cliente | Demonstração | Ferramentas | Segurança | Cenários | Documentação | Wiki

Por que ProxmoxMCP-Plus

O ProxmoxMCP-Plus fica entre clientes de IA e o Proxmox VE para que os operadores não precisem montar chamadas de API brutas, scripts shell avulsos e sondagens de trabalhos personalizadas para cada fluxo de trabalho.

Ele expõe a mesma superfície operacional de duas maneiras:

• MCP para Claude Desktop, Cursor, VS Code, Open WebUI, Codex e outros agentes compatíveis com MCP
• OpenAPI para automação HTTP, painéis, ferramentas internas e fluxos de trabalho sem código

O que você obtém:

• Ações de ciclo de vida de VM e LXC
• criação, reversão e exclusão de snapshots
• fluxos de trabalho de backup e restauração
• download e limpeza de ISO
• inspeção de nós, armazenamento e cluster
• execução de comandos em contêiner via SSH com proteções
• rastreamento persistente de trabalhos para tarefas assíncronas do Proxmox

O Que Torna Diferente

Prioridade	Como o projeto lida com isso
Caminhos de acesso duplos	MCP nativo para fluxos de trabalho de agentes e OpenAPI para automação HTTP padrão
Fluxos de trabalho orientados ao Proxmox	Operações de VM, LXC, snapshot, backup, ISO, armazenamento e cluster no dia 2
Operações de longa duração	job_ids estáveis, rastreamento de UPID do Proxmox, sondagem, repetição, cancelamento e histórico de auditoria
Execução mais segura	Tokens de API do Proxmox, autenticação bearer OpenAPI, política de comandos, tokens de aprovação, validação TLS e controles de Host/Origem HTTP do MCP
Validação real	Pontos de entrada de testes unitários, de integração, Docker/OpenAPI e e2e ao vivo do Proxmox documentados no repositório

Início Rápido

1. Prepare as Credenciais do Proxmox

Crie um token de API do Proxmox com apenas as permissões que seus fluxos de trabalho precisam. Em seguida, crie o arquivo de configuração local:

cp proxmox-config/config.example.json proxmox-config/config.json

Depois edite proxmox-config/config.json com seu ambiente. No mínimo, ele precisa de:

• proxmox.host
• proxmox.port
• auth.user
• auth.token_name
• auth.token_value

Adicione também uma seção ssh se quiser execução de comandos em contêiner. Adicione uma seção jobs se quiser que o estado dos trabalhos seja persistido em outro local que não o arquivo SQLite local padrão.

Para verificação real ao vivo, use um proxmox-config/config.live.json separado criado a partir de proxmox-config/config.live.example.json. Não aponte o e2e ao vivo para um config.json de espaço reservado ou somente local, a menos que você execute intencionalmente um túnel de API local lá.

Configuração opcional de persistência de trabalhos:

{
  "jobs": {
    "sqlite_path": "proxmox-jobs.sqlite3"
  }
}

A filtragem opcional de exposição de ferramentas pode reduzir os esquemas enviados aos clientes MCP. Ela está desabilitada por padrão, portanto as configurações existentes continuam expondo todas as ferramentas disponíveis. Configure exatamente um modo em mcp:

{
  "mcp": {
    "tool_allowlist": ["get_nodes", "get_vms", "get_containers", "get_storage"]
  }
}

Alternativamente, use tool_denylist, ou as variáveis de ambiente separadas por vírgula MCP_TOOL_ALLOWLIST e MCP_TOOL_DENYLIST. Não configure os dois modos. A seleção por ambiente substitui o modo de filtragem em nível de arquivo. Uma lista de permissões vazia não expõe nenhuma ferramenta; uma lista de bloqueios vazia não oculta nenhuma. Nomes exatos de ferramentas em minúsculas são obrigatórios, e nomes desconhecidos falham na inicialização para que um erro de digitação não amplie silenciosamente o acesso. Reinicie ou reconecte o servidor MCP após alterar o filtro.

2. Escolha um Caminho de Execução

Caminho	Melhor para	Comando de início	Verificar
MCP stdio do PyPI	Claude Desktop, Cursor, VS Code, Codex, agentes locais	uvx proxmox-mcp-plus	o cliente lista get_nodes, get_vms e ferramentas de trabalho
MCP HTTP nativo do Docker	clientes MCP remotos que suportam Streamable HTTP	docker compose --profile mcp-http up -d proxmox-mcp-http	conecte-se a http://localhost:8000/mcp
Ponte OpenAPI do Docker	clientes HTTP, painéis, scripts, ferramentas sem código	docker compose up -d	curl -f http://localhost:8811/livez

MCP stdio com PyPI

uvx proxmox-mcp-plus

Ou instale primeiro:

pip install proxmox-mcp-plus
proxmox-mcp-plus

Use este caminho quando o cliente MCP iniciar um servidor stdio local.

Modo de Código (opt-in)

O Modo de Código está desabilitado por padrão para preservar o catálogo completo de ferramentas legado. Habilite-o com mcp.code_mode: true no arquivo de configuração ou MCP_CODE_MODE=true. Quando habilitado, o MCP expõe três ferramentas em vez disso: proxmox_code_search, proxmox_code_get_schema e proxmox_code_execute. A execução de código ocorre em um sandbox isolado e alcança as ferramentas de domínio através do caminho existente de validação, política e aprovação. A descoberta usa o catálogo de execução filtrado, portanto também funciona em wheels instalados. Por exemplo:

await call_tool("get_nodes", {"target": "default"})

A expressão final é retornada como data.result; os resultados das ferramentas usam blocos de conteúdo JSON do MCP (e conteúdo estruturado quando fornecido). Use proxmox_code_get_schema para argumentos, incluindo target e tokens de aprovação. Os scripts não têm acesso a sistema de arquivos ou rede, exceto chamadas de ferramentas registradas. Limites: 64.000 caracteres de código-fonte, 100 MB de memória do sandbox, 25 chamadas de ferramentas, 16 KB de JSON final e duas execuções simultâneas. A execução tem um orçamento de 30 segundos; cancelar ou falhar um script não reverte os efeitos colaterais das ferramentas. Não repita automaticamente um script de mutação com falha.

Reutilização opcional de workers: defina mcp.code_mode_pool_reuse: true ou MCP_CODE_MODE_POOL_REUSE=true. O padrão permanece um worker novo por execução. A reutilização mantém até dois workers durante a vida útil do servidor, recicla cada um após 100 checkouts e inicia uma nova sessão de sandbox por solicitação. Globais, aprovações, coletores de saída e limites de chamadas não são compartilhados entre solicitações. Clientes HTTP compartilham o pool de propriedade do servidor; desconectar um cliente não o fecha. Execute python scripts/benchmark_code_mode.py para medir a sobrecarga local de inicialização; isso é um microbenchmark, não uma estimativa da latência das operações do Proxmox.

MCP HTTP nativo com Docker

Use este caminho quando um cliente MCP remoto suportar Streamable HTTP:

export MCP_API_KEY="$(openssl rand -hex 32)"
docker run --rm -p 8000:8000 \
  -e PROXMOX_MCP_MODE=mcp-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e MCP_TRANSPORT=STREAMABLE_HTTP \
  -e MCP_API_KEY="$MCP_API_KEY" \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

Aponte os clientes MCP para:

http://<docker-host>:8000/mcp

Envie Authorization: Bearer <MCP_API_KEY> com cada solicitação HTTP MCP nativa. A chave é independente das credenciais do Proxmox. Streamable HTTP nativo e SSE exigem uma chave por padrão. Para um endpoint protegido por uma camada externa de controle de acesso, como ACLs do Tailscale, defina explicitamente MCP_ALLOW_UNAUTHENTICATED_HTTP=true ou mcp.allow_unauthenticated_http: true na configuração JSON. Isso permite inicialização sem chave e registra um aviso; não configura nem verifica os controles de acesso externos. Um MCP_API_KEY configurado é sempre aplicado, mesmo com a opção de exclusão. Essa configuração não altera a autenticação OpenAPI nem a proteção contra rebinding de DNS.

Portão de navegador OAuth para clientes MCP

O MCP HTTP nativo pode opcionalmente expor um fluxo de código de autorização OAuth com PKCE enquanto mantém MCP_API_KEY como a única credencial humana que um operador precisa gerenciar. O tratamento do protocolo OAuth é delegado ao SDK Python do MCP (mcp>=1.30.0,<2), enquanto o ProxmoxMCP-Plus fornece a política de consentimento de chave de API e o estado OAuth persistente.

O estado OAuth é armazenado no PostgreSQL. Isso permite que vários workers ou hosts MCP compartilhem clientes registrados, códigos de autorização, tokens de acesso, tokens de atualização, proteção contra repetição de tokens de atualização e estado de limite de taxa de login sem depender de um sistema de arquivos local.

O cliente começa no endpoint /authorize do SDK. Após o SDK validar o cliente, URI de redirecionamento, escopo, solicitação PKCE e recurso, o navegador é redirecionado para /oauth/consent na mesma origem MCP. O usuário revisa o nome do cliente, origem de redirecionamento e escopos solicitados, e então insere MCP_API_KEY. A chave de API nunca é colocada em uma URL e nunca é retornada ao cliente OAuth.

Configurações OAuth obrigatórias:

export MCP_API_KEY="$(openssl rand -hex 32)"
export MCP_OAUTH_DATABASE_URL='postgresql://proxmox_oauth:secret@postgres.example:5432/proxmox_oauth'

Exemplo de servidor:

docker run --rm -p 8000:8000 \
  -e PROXMOX_MCP_MODE=mcp-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e MCP_TRANSPORT=STREAMABLE_HTTP \
  -e MCP_API_KEY="$MCP_API_KEY" \
  -e MCP_OAUTH_ENABLED=true \
  -e MCP_OAUTH_ISSUER=https://mcp.example.com \
  -e MCP_OAUTH_DATABASE_URL="$MCP_OAUTH_DATABASE_URL" \
  -e MCP_ALLOWED_HOSTS=mcp.example.com:*,localhost:* \
  -e MCP_ALLOWED_ORIGINS=https://mcp.example.com \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

Em seguida, conecte o cliente compatível com OAuth a:

https://mcp.example.com/mcp

O modo OAuth expõe estes endpoints na mesma origem pública:

• /.well-known/oauth-protected-resource/mcp - metadados de recurso protegido RFC 9728
• /.well-known/oauth-authorization-server - metadados do servidor de autorização do SDK
• /register - registro dinâmico de clientes (DCR) do SDK
• /authorize - endpoint de autorização do SDK
• /token - troca de código de autorização/token de atualização do SDK
• /oauth/consent - página de consentimento de chave de API do ProxmoxMCP-Plus

O SDK exige PKCE S256 e protege o recurso MCP com tokens de acesso OAuth emitidos. As transações de consentimento do navegador são de curta duração, assinadas com HMAC e sem estado. Todo o estado OAuth durável é armazenado no PostgreSQL.

O consumo de códigos de autorização e a rotação de tokens de atualização usam transações PostgreSQL. Um código ou token de atualização é excluído e seus tokens substitutos são inseridos atomicamente, portanto workers concorrentes não podem reproduzir com sucesso a mesma credencial. A capacidade de registro dinâmico de clientes também é serializada com um bloqueio consultivo com escopo de transação PostgreSQL; registros inativos são podados antes que o limite configurado seja excedido.

A rotação de chaves de API é versionada para segurança multi-worker. MCP_OAUTH_KEY_VERSION padrão é 1. Ao alterar MCP_API_KEY, incremente a versão ao mesmo tempo em cada novo worker. Uma versão mais alta invalida atomicamente os registros de clientes existentes e seus códigos/tokens dependentes. Um worker com uma versão mais antiga é rejeitado, e workers usando chaves diferentes com a mesma versão são rejeitados. Isso impede que um worker desatualizado reverta uma rotação de chave distribuída.

Obrigatório quando o OAuth está habilitado:

Variável	Finalidade
MCP_API_KEY	Credencial humana inserida apenas na página de consentimento
MCP_OAUTH_ISSUER	Origem HTTPS pública deste servidor de autorização MCP
MCP_OAUTH_DATABASE_URL	DSN PostgreSQL usado para o estado OAuth

Variáveis de ambiente OAuth opcionais:

Variável	Padrão	Finalidade
MCP_OAUTH_KEY_VERSION	1	Época monotônica da chave de API; incremente sempre que MCP_API_KEY mudar
MCP_OAUTH_RESOURCE	<issuer>/mcp	Identificador público do recurso MCP; deve usar a origem do emissor
MCP_OAUTH_SCOPES	mcp	Escopos obrigatórios separados por vírgula
MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS	3600	Tempo de vida do token de acesso
MCP_OAUTH_REFRESH_TOKEN_TTL_SECONDS	2592000	Tempo de vida do token de atualização (30 dias)
MCP_OAUTH_MAX_REGISTERED_CLIENTS	4096	Máximo de clientes DCR persistidos antes da poda de clientes inativos
MCP_OAUTH_DB_POOL_MIN_SIZE	1	Mínimo de conexões asyncpg por worker MCP
MCP_OAUTH_DB_POOL_MAX_SIZE	10	Máximo de conexões asyncpg por worker MCP
MCP_OAUTH_DB_COMMAND_TIMEOUT_SECONDS	10	Tempo limite de comando PostgreSQL usado pelo armazenamento OAuth
MCP_OAUTH_CLIENT_IP_HEADER	não definido	Cabeçalho de proxy reverso confiável usado apenas para limite de taxa de login

Para rotacionar a credencial do portão do navegador, implante a nova chave com uma versão mais alta, por exemplo:

MCP_API_KEY=<new-secret>
MCP_OAUTH_KEY_VERSION=2

Não reutilize um número de versão para uma chave diferente.

A função do banco de dados deve ser capaz de criar e modificar as tabelas proxmox_mcp_oauth_* em seu banco de dados. As tabelas contêm metadados de clientes OAuth, incluindo segredos de clientes emitidos, além de códigos de autorização e tokens ativos, portanto o banco de dados PostgreSQL e os backups devem ser protegidos como armazenamento de credenciais.

Se várias instâncias MCP usarem o mesmo MCP_OAUTH_DATABASE_URL, o estado OAuth e a aplicação de tokens de uso único são compartilhados entre elas. Dimensione o pool considerando o número total de workers MCP, pois os limites de pool configurados se aplicam por processo.

Se o servidor estiver atrás de um proxy reverso confiável e a limitação de taxa de login por usuário precisar usar o endereço original do cliente, defina MCP_OAUTH_CLIENT_IP_HEADER para um cabeçalho que o proxy sobrescreve (por exemplo, CF-Connecting-IP). Deixe-o não definido, a menos que o proxy impeça os clientes de falsificar esse cabeçalho.

Quando MCP_OAUTH_ENABLED=true, uma solicitação Authorization: Bearer <MCP_API_KEY> bruta para /mcp é rejeitada intencionalmente. A chave de API é aceita apenas pela página de consentimento; solicitações MCP devem usar um token de acesso OAuth emitido.

Ao servir MCP HTTP atrás de um proxy reverso, mantenha a proteção contra rebinding de DNS habilitada e permita apenas os hostnames que você espera.

Ponte OpenAPI com Docker

O modo OpenAPI é o runtime Docker padrão e requer uma chave de API:

export PROXMOX_API_KEY="$(openssl rand -hex 32)"
docker run --rm -p 8811:8811 \
  -e PROXMOX_API_KEY="$PROXMOX_API_KEY" \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

Verifique a superfície OpenAPI:

curl -f http://localhost:8811/livez
curl -f -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/health
curl -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/openapi.json

Para desenvolvimento local não autenticado apenas, defina PROXMOX_ALLOW_NO_AUTH=true.

Checkout do código-fonte

git clone https://github.com/RekklesNA/ProxmoxMCP-Plus.git
cd ProxmoxMCP-Plus
uv venv
uv pip install -e ".[dev]"
python main.py

O serviço 8811 é a ponte OpenAPI/REST. O serviço 8000 é o endpoint MCP HTTP nativo.

Instalação do Cliente

Use os botões de um clique quando seu cliente suportar deeplinks de instalação MCP, ou copie a configuração JSON abaixo.

Configuração stdio recomendada:

{
  "mcpServers": {
    "proxmox-mcp-plus": {
      "command": "uvx",
      "args": ["proxmox-mcp-plus"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-host",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "mcp-token",
        "PROXMOX_TOKEN_VALUE": "your-token-secret",
        "PROXMOX_PORT": "8006",
        "PROXMOX_VERIFY_SSL": "true"
      }
    }
  }
}

Use um arquivo de configuração local se preferir não manter credenciais na configuração do cliente:

{
  "mcpServers": {
    "proxmox-mcp-plus": {
      "command": "uvx",
      "args": ["proxmox-mcp-plus"],
      "env": {
        "PROXMOX_MCP_CONFIG": "/path/to/ProxmoxMCP-Plus/proxmox-config/config.json"
      }
    }
  }
}

Exemplos específicos de cliente para Claude Desktop, Cursor, VS Code, Codex, OpenCode, Open WebUI, Streamable HTTP e OpenAPI estão no Guia de Configuração do Cliente e no Guia de Integrações.

Demonstração

Esta demonstração é uma gravação direta de terminal do qwen/qwen3.6-plus dirigindo uma sessão MCP ao vivo em inglês contra um laboratório Proxmox local. Ela mostra controle em linguagem natural fluindo através das ferramentas MCP para criar e iniciar um LXC, executar um comando no contêiner e confirmar a superfície HTTP /health autenticada.

Assista à versão MP4

Escolha a Ferramenta Certa

Comece com descoberta somente leitura, depois passe para ferramentas de mutação apenas após o nó alvo, armazenamento, VMID e permissões estarem claros.

Objetivo do operador	Comece com	Depois use	Notas
Inspecionar o cluster	get_nodes, get_cluster_status	get_storage, get_vms, get_containers	Melhor primeira verificação de saúde após a instalação do cliente
Criar ou gerenciar uma VM	get_nodes, get_storage	create_vm, start_vm, stop_vm, delete_vm	Mutações de longa duração retornam job_id e Proxmox task_id
Gerenciar LXCs	get_containers, get_storage	create_container, start_container, stop_container, delete_container	Ferramentas de comando via SSH exigem a configuração opcional ssh
Reverter mudanças arriscadas	list_snapshots com vm_type=qemu ou vm_type=lxc	create_snapshot, rollback_snapshot, delete_snapshot	Crie um snapshot antes de testes de fluxo de trabalho destrutivos
Executar comandos dentro de convidados	Ferramentas de status de VM ou contêiner	execute_vm_command, execute_container_command	O caminho da VM precisa do QEMU Guest Agent; o caminho LXC precisa de SSH para o nó Proxmox
Rastrear trabalho assíncrono	resposta de mutação com job_id	poll_job, get_job, list_jobs, retry_job, cancel_job	Use job_id para conversas agente/usuário e task_id para rastreabilidade bruta do Proxmox
Inspecionar logs	get_node_syslog, get_cluster_log	get_task_log, get_node_firewall_log, get_guest_firewall_log	Todas as ferramentas de log são somente leitura; get_task_log aceita qualquer UPID do Proxmox
Automatizar a partir de ferramentas HTTP	/openapi.json	/jobs, /health, rotas de ferramentas geradas	Use autenticação bearer e mantenha CORS restrito fora do desenvolvimento local

Para o mapa completo de ferramentas, veja o Guia de Seleção de Ferramentas e a Referência de API e Ferramentas.

Modelo de Segurança

ProxmoxMCP-Plus é uma camada de acesso, não um substituto para o RBAC do Proxmox, controles de rede ou prompts de aprovação MCP do lado do cliente.

O projeto dá aos operadores vários pontos de controle:

• Tokens de API do Proxmox decidem o que o backend pode fazer.
• PROXMOX_API_KEY protege a ponte OpenAPI por padrão.
• MCP_API_KEY protege Streamable HTTP nativo e SSE com autenticação Bearer; é obrigatório, a menos que MCP_ALLOW_UNAUTHENTICATED_HTTP=true delegue explicitamente o controle de acesso.
• A verificação TLS é aplicada, a menos que o modo de desenvolvimento seja explicitamente habilitado.
• command_policy controla a execução de comandos e operações de alto risco.
• approval_token pode controlar a execução de comandos e ações de mutação de alto risco.
• Implantações MCP Streamable HTTP podem usar proteção contra rebinding de DNS mais listas de permissão de Host e Origin.
• Listas de permissão ou bloqueio opcionais de ferramentas MCP reduzem a superfície de ferramentas em runtime; elas não substituem o RBAC do Proxmox.
• Os logs são projetados para evitar expor material de comandos e credenciais.

Leia o Guia de Segurança antes de expor o servidor fora de um ambiente local confiável.

Capacidades Principais da Plataforma

ProxmoxMCP-Plus fornece uma superfície de controle unificada para as tarefas operacionais que a maioria das equipes realmente precisa no Proxmox VE. O mesmo servidor pode expor esses fluxos de trabalho a clientes MCP para casos de uso de LLM e agentes de IA, e a consumidores HTTP através da ponte OpenAPI.

Áreas de fluxo de trabalho suportadas:

Área de Capacidade	Disponibilidade
Criar / iniciar / parar / excluir VM	Disponível
Criar / reverter / excluir snapshot de VM	Disponível
Criar / restaurar backup	Disponível
Baixar / excluir ISO	Disponível
Criar / iniciar / parar / excluir LXC	Disponível
Execução de comandos em contêiner via SSH	Disponível
Atualização de authorized_keys em contêiner	Disponível
Armazenamento persistente de jobs para tarefas longas	Disponível
Ferramentas de controle de jobs MCP (list_jobs, get_job, poll_job, cancel_job, retry_job)	Disponível
Endpoints OpenAPI /jobs com códigos de status explícitos	Disponível
OpenAPI local /livez, /readyz, /health e schema	Disponível
Docker nativo MCP Streamable HTTP em /mcp	Disponível
Build de imagem Docker e /livez	Disponível

Pontos de entrada de validação e contrato neste repositório:

• pytest -q --cov=proxmox_mcp --cov-report=term-missing --cov-fail-under=75
• ruff check .
• mypy src --ignore-missing-imports
• pip-audit -r requirements.txt
• tests/integration/test_real_contract.py
• tests/scripts/run_real_e2e.py

tests/scripts/run_real_e2e.py agora prefere proxmox-config/config.live.json ou PROXMOX_MCP_E2E_CONFIG. Isso evita executar acidentalmente verificações ao vivo contra um config.json padrão específico da máquina.

Jobs de Longa Duração

Muitas mutações do Proxmox são assíncronas. ProxmoxMCP-Plus agora envolve essas tarefas em uma camada de jobs persistente para que clientes MCP e OpenAPI possam rastreá-las através de um Job ID estável.

Ferramentas de longa duração, como criar/iniciar/parar VM, criar/iniciar/parar contêiner, mudanças de snapshot, backup/restauração e download/exclusão de ISO, agora retornam ambos:

• task_id: o UPID bruto do Proxmox
• job_id: o registro de job estável no lado do servidor

O registro de job armazena:

• status atual e progresso
• contagem de tentativas e UPIDs anteriores
• payload de resultado mais recente ou motivo de falha
• histórico de auditoria para ações de criar, consultar, tentar novamente e cancelar

Por padrão, o armazenamento de jobs persiste em proxmox-jobs.sqlite3, então reiniciar não perde metadados de jobs em andamento ou concluídos.

Eventos de auditoria são anexados a uma tabela SQLite separada. O histórico existente é migrado na inicialização e o formato audit_log da API permanece inalterado. A retenção é ilimitada por padrão; defina jobs.audit_retention_days para um número positivo na configuração JSON para podar eventos expirados na inicialização e quando cada job é atualizado. Isso nunca exclui o próprio job. Pare todos os workers que compartilham o banco de dados e faça backup dele antes desta atualização. Não execute versões antigas e novas contra o mesmo banco de dados; restaure o backup pré-atualização se fizer downgrade e reter o histórico de auditoria for necessário.

Uma solicitação de cancelamento não é conclusão. Consulte até que a tarefa esteja falha/cancelada antes de chamar retry_job; cancelamento pendente não pode ser tentado novamente.

Ferramentas de Job MCP

• list_jobs
• get_job
• poll_job
• cancel_job
• retry_job

Rotas de Job OpenAPI

Quando o proxy OpenAPI está habilitado e um JobStore local está disponível, estas rotas são expostas diretamente:

Caminho	Método	Propósito	Códigos de Sucesso
/jobs	GET	listar jobs persistidos	200
/jobs/{job_id}	GET	buscar um job, opcional refresh=true	200
/jobs/{job_id}/poll	POST	atualizar status do Proxmox	200
/jobs/{job_id}/cancel	POST	solicitar cancelamento	202
/jobs/{job_id}/retry	POST	reproduzir uma receita de tentativa armazenada	202

Códigos de erro comuns:

• 404: job_id desconhecido
• 409: o job existe, mas essa operação não é válida agora
• 503: o proxy OpenAPI foi iniciado sem um JobStore local

tests/scripts/run_real_e2e.py agora prefere proxmox-config/config.live.json ou PROXMOX_MCP_E2E_CONFIG. Isso evita executar acidentalmente verificações ao vivo contra um config.json padrão específico da máquina.

Posicionamento Contra Abordagens Comuns

Capacidade	API Oficial do Proxmox	Scripts avulsos	ProxmoxMCP-Plus
MCP para fluxos de trabalho de LLM e agentes de IA	Não	Não	Sim
Superfície OpenAPI para ferramentas HTTP padrão	Não	Geralmente não	Sim
Operações de VM e LXC em uma interface	Somente baixo nível	Depende	Sim
Fluxos de trabalho de snapshot, backup e restauração	Somente baixo nível	Depende	Sim
Rastreamento e tentativa de jobs assíncronos persistentes	Não	Raro	Sim
Execução de comandos em contêiner com controles de política	Não	Somente personalizado	Sim
Caminho de distribuição Docker	Não	Raro	Sim
Verificação de ambiente ao vivo em nível de repositório	N/A	Raro	Sim

Modelos de Cenário

Exemplos prontos para copiar estão em docs/examples/:

• Criar uma VM de teste
• Reverter uma mudança arriscada com snapshots
• Baixar um ISO e criar um LXC

Estes são escritos tanto para operadores humanos quanto para uso orientado por LLM.

Documentação

O README é intencionalmente otimizado para compreensão rápida no GitHub. Documentação operacional mais longa vive em docs/wiki/ e também pode ser publicada no Wiki do GitHub.

Se você precisar...	Comece aqui
Entender o projeto e o fluxo de implantação	Página Inicial do Wiki
Configurar e executar contra um ambiente Proxmox	Guia do Operador
Conectar Claude Desktop, Cursor, VS Code, Codex, Open WebUI ou clientes HTTP	Guia de Configuração do Cliente
Escolher a ferramenta certa para um fluxo de trabalho	Guia de Seleção de Ferramentas
Revisar metas de qualidade de docs, plano de mídia e checklist de publicação	Plano de Qualidade de Documentação
Revisar padrões de integração e detalhes de transporte	Guia de Integrações
Instalar a partir de IDEs e agentes com suporte a MCP	Instalação de Agente
Habilitar execução de comandos LXC via SSH	Execução de Comandos em Contêiner
Revisar segurança e política de comandos	Guia de Segurança
Inspecionar parâmetros, pré-requisitos e comportamento de ferramentas	Referência de API e Ferramentas
Depurar problemas de inicialização, autenticação ou saúde	Solução de Problemas
Trabalhar no código-fonte ou lançá-lo	Guia do Desenvolvedor
Revisar notas de lançamento e atualização	Notas de Lançamento e Atualização

Wiki publicado:

• Página Inicial do Wiki GitHub

Layout do Repositório

• src/proxmox_mcp/: servidor MCP, carregamento de configuração, segurança, ponte OpenAPI
• main.py: ponto de entrada MCP para uso local e orientado a cliente
• docker-compose.yml: runtime HTTP/OpenAPI
• requirements/: fontes auxiliares de dependências e listas de instalação em runtime
• scripts/: scripts de inicialização auxiliares para fluxos de trabalho locais
• tests/scripts/run_real_e2e.py: caminho Proxmox e Docker/OpenAPI ao vivo
• tests/: cobertura de testes unitários e de integração
• docs/examples/: prompts orientados a cenários e exemplos HTTP
• docs/wiki/: documentação de operador, integração e referência em formato mais longo

Verificações de Desenvolvimento

pytest -q --cov=proxmox_mcp --cov-report=term-missing --cov-fail-under=75
ruff check .
mypy src --ignore-missing-imports
pip-audit -r requirements.txt
python -m build

Paramiko 5.0.0 ou mais recente é necessário para que pip-audit possa ser executado sem uma exceção CVE-2026-44405.

Licença

MIT

Instalação de ISO e configuração de rede LXC

Use list_isos para encontrar um volume ISO existente (ou download_iso para obter um). create_vm aceita iso_volume="local:iso/debian.iso", monta-o em ide3 por padrão e inicializa o CD-ROM antes do disco. update_vm_config pode montar ou alterar essa ISO, ejetar com iso_volume="none", definir boot_order="scsi0;ide3" ou alterar network_bridge em net0 mantendo as configurações de MAC/VLAN/firewall. Escolha um cdrom_device livre; discos de dados existentes e unidades cloud-init nunca são substituídos. Edições de mídia e bridge leem a configuração atual e, portanto, precisam de VM.Audit bem como dos privilégios de configuração relevantes. Atualizações existentes apenas de dimensionamento/cloud-init ainda não exigem uma leitura preliminar.

LXC usa modelos de SO, não ISOs de instalador. create_container mantém DHCP por padrão e agora aceita network_bridge, ip="192.168.1.50/24", gw="192.168.1.1", ip6 e gw6. update_container_network edita esses campos em uma interface existente (padrão net0, selecionável por meio de net31) e preserva todas as opções não especificadas. Use uma string de gateway vazia para removê-lo; alterar para DHCP/manual remove o gateway antigo para aquela família de endereços. Alterações de rede podem interromper a conectividade do convidado. Ambas as ferramentas de edição seguem políticas de aprovação de alvo nomeado, somente leitura e alto risco. Adicione update_container_network às listas personalizadas de alto risco e às allowlists de ferramentas desejadas. Consulte as notas de versão v0.5.19 para detalhes de atualização.