Skills MCP Veeam Backup Pro

---

📑 Índice

• Visão Geral
• Por Que Arquitetura Híbrida?
• Comparação: Hybrid vs MCPO
• Principais Recursos
• Arquitetura
• Instalação
• Configuração
• Modo de Uso
• Ferramentas Disponíveis
• Integração com IDEs
• Exemplos Práticos
• Segurança
• Contribuindo
• Licença
• Créditos
• Suporte

---

🎯 Visão Geral

O Veeam Backup & Replication MCP Server é uma implementação completa do Model Context Protocol (MCP) HTTP Streamable (2024-11-05) que permite que assistentes de IA (Claude Code, Gemini CLI, Claude Desktop) interajam diretamente com sua infraestrutura de backup Veeam VBR através de linguagem natural, com autenticação Bearer Token e gerenciamento de sessões.

O Que É MCP?

Model Context Protocol (MCP) é um protocolo aberto que permite que modelos de IA acessem dados contextuais e executem ações em sistemas externos de forma estruturada e segura.

O Que Este MCP Faz?

Permite que você faça perguntas e execute ações no Veeam VBR usando linguagem natural:

Monitoramento e Consultas:

• ✅ "Mostre todos os jobs de backup que falharam hoje"
• ✅ "Qual o status atual dos repositórios de backup?"
• ✅ "Liste os últimos 5 backups do servidor SQL-PROD"
• ✅ "Quantas licenças Veeam tenho disponíveis?"
• ✅ "Me mostre informações detalhadas do job 'VM-Production-Backup'"

Controle e Troubleshooting:

• ✅ "Quais backups estão rodando agora?"
• ✅ "Me mostre os restore points disponíveis para a VM 'SQL-SERVER-01'"
• ✅ "Liste os jobs de backup copy configurados para compliance 3-2-1"
• ✅ "Qual o próximo agendamento do job 'Daily-Full-Backup'?"
• ✅ "Me mostre os logs detalhados da última sessão de backup do job 'Exchange-Backup'"

Tudo isso sem sair do chat da IA!

---

💼 Precisa de Ajuda com Veeam Backup ou IA?

A Skills IT - Soluções em Tecnologia é especialista em infraestrutura de TI e domina profundamente Veeam Backup & Replication. Nossa equipe possui expertise em Inteligência Artificial e Model Context Protocol (MCP), oferecendo soluções completas para automação e integração de sistemas.

Nossos Serviços:

• ✅ Consultoria e implementação Veeam Backup & Replication
• ✅ Desenvolvimento de MCPs customizados para sua infraestrutura
• ✅ Integração de IA com sistemas corporativos
• ✅ Automação de processos de backup e recuperação
• ✅ Treinamento e suporte especializado

📞 WhatsApp/Telefone: (63) 3224-4925 - Brasil 🌐 Website: skillsit.com.br 📧 Email: [email protected]

"Transformando infraestrutura em inteligência"

---

🏗️ Por Que Arquitetura Híbrida?

Este não é apenas mais um MCP Server. É uma arquitetura híbrida única que resolve um problema real:

❌ Problema Comum

Servidores MCP tradicionais funcionam apenas com clientes MCP nativos (como Claude Desktop via stdio). Para usar com outras ferramentas (Copilot Studio, APIs web), você precisa:

1. Instalar um proxy externo (como MCPO)
2. Configurar roteamento entre proxy e MCP
3. Gerenciar dois serviços separados
4. Debugar duas camadas de comunicação

✅ Solução Híbrida

Nosso servidor executa dois protocolos simultaneamente em um único processo:

1. Modo MCP (stdio): Para Claude Desktop, Claude Code
2. Modo HTTP (REST): Para Copilot Studio, Gemini CLI, APIs web
3. Modo Híbrido: Ambos ao mesmo tempo (recomendado)

Resultado: Um servidor, uma configuração, zero dependências externas.

---

📊 Comparação: Hybrid vs MCPO

Característica	Hybrid (Este Projeto)	MCPO (Proxy Externo)	MCP Tradicional
Arquitetura	MCP + HTTP integrados	MCP → Proxy → HTTP	Apenas MCP (stdio)
Deployment	✅ Único serviço	⚠️ Dois serviços	✅ Único serviço
Performance	✅ Zero overhead	⚠️ Hop adicional	✅ Direto
Complexidade	✅ Simples	⚠️ Complexo	✅ Simples
Claude Desktop	✅ Suportado	✅ Suportado	✅ Suportado
Copilot Studio	✅ Suportado	✅ Suportado	❌ Não suportado
APIs Web/Custom	✅ Suportado	✅ Suportado	❌ Não suportado
Swagger UI	✅ Incluído	⚠️ Depende do proxy	❌ Não disponível
Manutenção	✅ Um codebase	⚠️ Dois codebases	✅ Um codebase
Logs	✅ Centralizados	⚠️ Dois streams	✅ Centralizados
Autenticação	✅ Automática	⚠️ Manual	⚠️ Manual

Conclusão: A arquitetura híbrida oferece a melhor relação custo-benefício para ambientes que precisam de compatibilidade universal.

---

🚀 Principais Recursos

🔄 Arquitetura Híbrida Única

• Modo MCP (stdio): Compatível com Claude Desktop e clientes MCP nativos
• Modo HTTP (REST): Compatível com Copilot Studio, Gemini CLI, APIs web
• Modo Híbrido: Execute ambos simultaneamente (recomendado)
• Zero Dependências Externas: Sem necessidade de MCPO ou proxies

🛠️ 12 Ferramentas Veeam (v2.0.0)

Categoria	Ferramenta	Descrição
Busca	veeam_search_backup_jobs	Jobs de backup (VMs, replicação, cópia)
Busca	veeam_search_backup_sessions	Sessions/histórico de execuções
Busca	veeam_search_restore_points	Pontos de restauração de VMs
Busca	veeam_search_infrastructure	Proxies e repositórios de backup
Gerenciamento	veeam_manage_backup_jobs	Detalhes, schedule, iniciar ou parar jobs
Gerenciamento	veeam_manage_backup_sessions	Logs de sessions para troubleshooting
Consulta	veeam_get_license_compliance	Licenciamento, compliance e workloads
Consulta	veeam_get_server_info	Versão do VBR, banco de dados, build
Bridge	veeam_list_mcp_resources	Catálogo de resources MCP disponíveis
Bridge	veeam_read_mcp_resource	Leitura de resources via URI veeam://
Bridge	veeam_list_mcp_prompts	Catálogo de 15 prompts disponíveis
Bridge	veeam_get_mcp_prompt	Execução de prompt/workflow específico

Pattern: search_* (somente leitura) / manage_* (leitura + escrita) / get_* (recurso único)

🔍 Busca Semântica: Ferramentas veeam_search_backup_jobs e veeam_search_restore_points suportam busca semântica inteligente (multi-palavra, normalização de acentos, busca parcial).

v2.0.0 Melhorias

• 91% redução de tokens: Respostas Markdown em vez de JSON bruto
• 12 tools consolidadas: Pattern search_*/manage_*/get_* (Block recommendation)
• Tool Annotations: readOnlyHint, destructiveHint, openWorldHint em todas as tools
• Server Instructions: Guia operacional para LLM no initialize
• MCP Resources: Dados estáticos (server-info, license) via URI veeam://
• Bridge Tools MCPHub: Resources e Prompts acessíveis via tools
• Validação UUID: Erros claros antes de chamar API
• Testes automatizados: 74 testes (unit + integration)

🔒 Autenticação Automática Inteligente

• Middleware Transparente: Autenticação automática com credenciais do .env
• Token Caching: Cache de token por 55 minutos (evita re-autenticações)
• Promise Memoization: Previne race conditions em chamadas concorrentes
• Zero Configuração: Ferramentas não precisam gerenciar autenticação

📚 Documentação Interativa

• Swagger UI: Documentação interativa em /docs
• OpenAPI 3.0: Especificação completa em /openapi.json
• Health Check: Endpoint /health com status de autenticação
• Exemplos de Código: Snippets prontos para uso

🔧 Operação Flexível

• Protocolo MCP HTTP Streamable (2024-11-05): Compatível com Claude Code e Gemini CLI
• Autenticação Bearer Token: Segurança integrada via header Authorization
• Session Management: Gerenciamento de sessões com UUID e timeout de 15 minutos
• PM2 Ready: Gerenciamento de processo em produção
• Docker Support: Containerização completa com docker-compose
• Environment Variables: Configuração via .env

---

🏛️ Arquitetura

Diagrama de Arquitetura

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Claude Desktop │    │  Copilot Studio  │    │   Gemini CLI    │
│  (MCP Client)   │    │ (OpenAPI Client) │    │ (HTTP Client)   │
└────────┬────────┘    └─────────┬────────┘    └────────┬────────┘
         │                        │                       │
         │ stdio                  │ HTTP                  │ HTTP
         │                        │                       │
         ▼                        ▼                       ▼
┌─────────────────────────────────────────────────────────────────┐
│           Veeam Backup & Replication MCP Server                 │
│                     (Hybrid Architecture)                       │
│                                                                 │
│  ┌─────────────────┐         ┌─────────────────────────────────┐ │
│  │   MCP Mode      │         │      HTTP/OpenAPI Mode          │ │
│  │   (stdio)       │         │      (Express.js)               │ │
│  │                 │         │                                 │ │
│  │ • McpServer     │         │ • REST Endpoints                │ │
│  │ • Tool Registry │         │ • Swagger UI (/docs)            │ │
│  │ • stdio Transport│        │ • OpenAPI 3.0 (/openapi.json)  │ │
│  └─────────────────┘         └─────────────────────────────────┘ │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │        Autenticação Automática (Middleware)                 │ │
│  │  • Token Cache (55 min)                                     │ │
│  │  • Promise Memoization                                      │ │
│  │  • Refresh Automático                                       │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              18 Ferramentas Compartilhadas                  │ │
│  │  Jobs | Control | Sessions | Restore | Infra | License     │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                               │
                               │ HTTPS (Port 9419)
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│           Veeam Backup & Replication Server (VBR)               │
│                       REST API v1.2-rev0                        │
│                                                                 │
│  • Jobs de Backup          • Repositórios                       │
│  • Sessões de Backup       • Licenciamento                      │
│  • Servidores Proxy        • Configurações                      │
└─────────────────────────────────────────────────────────────────┘

Fluxo de Execução

1. Cliente envia requisição (stdio ou HTTP)
2. Middleware autentica automaticamente com Veeam (cache de token)
3. Tool Handler executa lógica de negócio
4. Veeam API processa requisição e retorna dados
5. Resposta formatada retorna ao cliente

---

📦 Instalação

Pré-requisitos

• Node.js 20+ (LTS recomendado)
• Veeam Backup & Replication 12+ com REST API habilitado
• Credenciais Veeam com permissões de leitura
• Acesso de rede ao servidor Veeam (porta 9419)

Método 1: NPM Install (Recomendado)

# Clone o repositório
git clone https://github.com/DevSkillsIT/Skills-MCP-Veeam-Backup-Pro.git
cd Skills-MCP-Veeam-Backup-Pro

# Instale dependências
npm install

# Configure variáveis de ambiente
cp env.example .env
nano .env

# Inicie o servidor (modo híbrido)
npm start

Método 2: Docker

# Clone o repositório
git clone https://github.com/DevSkillsIT/Skills-MCP-Veeam-Backup-Pro.git
cd Skills-MCP-Veeam-Backup-Pro

# Configure variáveis de ambiente
cp env.example .env
nano .env

# Inicie com Docker Compose
docker-compose up -d

# Verifique logs
docker-compose logs -f

Método 3: PM2 (Produção)

# Instale PM2 globalmente
npm install -g pm2

# Inicie o servidor com PM2
pm2 start vbr-mcp-server.js --name mcp-veeam -- --port=8825

# Salve configuração PM2
pm2 save

# Configure PM2 para iniciar no boot
pm2 startup

---

⚙️ Configuração

Variáveis de Ambiente (.env)

Copie env.example para .env e configure:

Variável	Obrigatório	Descrição	Exemplo
VEEAM_HOST	✅ Sim	Hostname ou IP do servidor Veeam	veeam.empresa.com
VEEAM_PORT	⚠️ Opcional	Porta da API REST (padrão: 9419)	9419
VEEAM_API_VERSION	⚠️ Opcional	Versão da API (padrão: 1.2-rev0)	1.2-rev0
VEEAM_USERNAME	✅ Sim	Usuário Veeam (formato: .\\usuário para local)	.\\admin
VEEAM_PASSWORD	✅ Sim	Senha do usuário Veeam	SenhaSegura123!
VEEAM_IGNORE_SSL	⚠️ Opcional	Ignorar erros SSL (padrão: true)	true
HTTP_PORT	⚠️ Opcional	Porta do servidor HTTP (padrão: 8825)	8825
AUTH_TOKEN	✅ Sim	Token de autenticação Bearer para MCP	bf2571ca23445da...
NODE_ENV	⚠️ Opcional	Ambiente de execução	production

Exemplo de Arquivo .env

# Veeam Server Configuration
VEEAM_HOST=veeam-prod.skillsit.local
VEEAM_PORT=9419
VEEAM_API_VERSION=1.2-rev0

# Authentication (Local User)
VEEAM_USERNAME=.\\veeam-admin
VEEAM_PASSWORD=SuperSecureP@ssw0rd2024

# Authentication (Domain User - Alternative)
# VEEAM_USERNAME=DOMAIN\\administrator
# VEEAM_PASSWORD=SuperSecureP@ssw0rd2024

# SSL Configuration
VEEAM_IGNORE_SSL=true

# Server Configuration
HTTP_PORT=8825
NODE_ENV=production

# MCP HTTP Streamable Authentication
AUTH_TOKEN=SEU_TOKEN_AQUI

Boas Práticas de Segurança

1. NUNCA commite o arquivo .env ao repositório Git
2. Use contas de serviço com permissões mínimas necessárias (read-only)
3. Rotacione senhas regularmente (a cada 90 dias)
4. Habilite SSL/TLS em produção (VEEAM_IGNORE_SSL=false)
5. Restrinja acesso à porta HTTP via firewall (apenas IPs confiáveis)
6. Use autenticação de domínio quando possível (mais seguro que usuário local)

---

🎮 Modo de Uso

3 Modos de Operação

Modo 1: Híbrido (Recomendado) ⭐

Execute ambos os protocolos simultaneamente:

# Via NPM
npm start

# Via Node.js
node vbr-mcp-server.js

# Via PM2
pm2 start vbr-mcp-server.js --name mcp-veeam -- --port=8825

Use quando:

• Você precisa de Claude Desktop E Copilot Studio
• Quer máxima flexibilidade
• Está em ambiente de produção

Modo 2: MCP-Only (stdio)

Execute apenas o protocolo MCP:

# Via NPM
npm run start:mcp

# Via Node.js
node vbr-mcp-server.js --mcp

# Via PM2
pm2 start vbr-mcp-server.js --name mcp-veeam-stdio -- --mcp

Use quando:

• Você usa apenas Claude Desktop ou Claude Code
• Não precisa de acesso HTTP/API
• Quer mínimo de overhead de rede

Modo 3: HTTP-Only (REST)

Execute apenas o servidor HTTP:

# Via NPM (porta padrão 8825)
npm run start:http

# Via Node.js (porta customizada)
node vbr-mcp-server.js --http --port=8825

# Via PM2
pm2 start vbr-mcp-server.js --name mcp-veeam-http -- --http --port=8825

Use quando:

• Você usa apenas Copilot Studio ou Gemini CLI
• Precisa de acesso via API REST
• Quer documentação Swagger UI

---

Ferramentas Disponíveis (v2.0.0)

O Veeam MCP v2.0.0 consolidou as 17 ferramentas originais em 12 ferramentas otimizadas seguindo o padrão search_*/manage_*/get_* (Block recommendation). Todas as respostas são formatadas em Markdown (redução de ~91% em tokens vs JSON bruto).

Ferramentas de Busca (search_*) — Somente Leitura

Tool	Descrição	Parâmetros Principais
veeam_search_backup_jobs	Jobs de backup, cópia e jobs derivados de sessões (Agent/replica/site remoto)	nameFilter (job OU nome de VM), descriptionFilter, typeFilter, stateFilter
veeam_search_backup_sessions	Sessions/histórico de execuções	statusFilter, scope, hours, from/to, groupByJob (1 linha por job)
veeam_search_restore_points	Pontos de restauração de VMs (com span de retenção)	vmName ou vmId, from/to
veeam_search_infrastructure	Proxies e repositórios (status CRÍTICO/ATENÇÃO/OFFLINE)	type (proxies/repositories), threshold

Ferramentas de Gerenciamento (manage_*) — Leitura + Escrita

Tool	Descrição	Actions
veeam_manage_backup_jobs	Detalhes, schedule, iniciar ou parar jobs	get_details, get_schedule, start, stop
veeam_manage_backup_sessions	Logs de sessions para troubleshooting	get_log (com logLevel filter)

Ferramentas de Consulta (get_*) — Somente Leitura

Tool	Descrição
veeam_get_license_compliance	Licenciamento, compliance e workloads protegidos
veeam_get_server_info	Versão do VBR, banco de dados, build

Bridge Tools MCPHub

Tool	Descrição
veeam_list_mcp_resources	Catálogo de resources MCP disponíveis
veeam_read_mcp_resource	Leitura de resources via URI veeam://
veeam_list_mcp_prompts	Catálogo de 15 prompts disponíveis
veeam_get_mcp_prompt	Execução de prompt/workflow específico

MCP Resources (Dados Estáticos)

URI	Descrição
veeam://server-info	Informações do servidor VBR
veeam://license	Dados de licenciamento e workloads

Recursos Avançados (alinhados ao código atual)

• groupByJob=true em search_backup_sessions: agrega as N tentativas de cada job em uma linha (último resultado, tentativas, falhas), com jobs falhando no topo — a visão de saúde do ambiente.
• Cobertura híbrida: search_backup_jobs encontra jobs fora do inventário /jobs (Veeam Agent, replica, backup copy, site remoto) derivando-os do histórico de sessões. Busca também por nome de VM dentro do job.
• Datas flexíveis (from/to): aceitam ISO (2026-05-28), BR (28/05/2026 05:30) e natural (ontem, últimas 6 horas, 7 dias).
• Resolução nome→UUID: manage_backup_jobs aceita o nome (parcial) do job; se casar vários, retorna os candidatos. start/stop exigem nome exato e único.
• get_log com resultado por VM: em jobs multi-VM, detalha quais VMs falharam e a causa de cada uma (aba Statistics do console), agrupando VMs com o mesmo erro.
• Span de retenção: search_restore_points mostra o primeiro e o último ponto da VM, e retorna candidatos quando o nome casa várias VMs distintas.

Exemplos de Uso

Buscar sessions com falha das últimas 24h:

curl -X POST http://localhost:8825/mcp \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"veeam_search_backup_sessions","arguments":{"statusFilter":"Failed","hours":24,"limit":10}},"id":1}'

Ver detalhes de um job:

curl -X POST http://localhost:8825/mcp \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"veeam_manage_backup_jobs","arguments":{"action":"get_details","jobId":"UUID-DO-JOB"}},"id":1}'

Verificar uso de repositórios:

curl -X POST http://localhost:8825/mcp \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"veeam_search_infrastructure","arguments":{"type":"repositories"}},"id":1}'

Tool Annotations

Todas as ferramentas possuem annotations MCP para segurança automática:

Annotation	Significado	Exemplo
readOnlyHint: true	Não modifica dados (auto-aprovável)	search_*, get_*
destructiveHint: true	Pode modificar dados (requer confirmação)	manage_backup_jobs (start/stop)
openWorldHint: true	Acessa API externa (latência possível)	Todas exceto list_mcp_*
idempotentHint: true	Chamadas repetidas são seguras	search_*, get_*

Formato de Resposta: Markdown

Todas as respostas são formatadas em Markdown (tabelas), não JSON bruto:

**5 resultados** | Pagina 1 (total: 9646, limit: 5)

| ID | Nome | Tipo | Resultado | Inicio | Duracao | Progresso |
|---|---|---|---|---|---|---|
| 12dc2486... | BKP-JOB-LOCAL-SK-PMW... | BackupJob | Sucesso | 22/03/2026 12:00 | 5 min | 100% |

Benefícios do Markdown vs JSON bruto:

• 91% menos tokens por resposta (testado com dados reais)
• Tabelas legíveis diretamente no chat
• Paginação com informação de total

Limites de Paginação

Parâmetro	Default	Máximo
limit	35	50
skip	0	—

Limites otimizados para evitar token explosion. Use skip para navegar páginas.

---

🔐 Nota sobre Safety Guard

As ações start e stop de veeam_manage_backup_jobs são protegidas por Tool Annotations (destructiveHint: true) devido ao impacto potencial:

• Requerem confirmação explícita via token
• Justificativa obrigatória com mínimo 10 caracteres
• Logs de auditoria registram quem executou e por quê
• Podem ser desabilitados via MCP_SAFETY_GUARD=false no .env (NÃO recomendado em produção)

Como obter o token: O token está configurado no .env do servidor MCP como MCP_SAFETY_TOKEN.

---

📋 MCP Prompts

Este MCP oferece 15 prompts profissionais (workflows pré-configurados) que guiam você através de operações complexas de Veeam Backup & Replication usando linguagem natural.

O Que São Prompts MCP? Prompts são templates de conversação reutilizáveis que estruturam tarefas multi-passo em workflows guiados. Em vez de executar uma única ação, prompts orquestram múltiplas ferramentas e fornecem análises contextuais.

Como Usar Prompts:

• Claude Code: Use o comando /prompt seguido do nome do prompt
• Claude Desktop: Digite "use prompt [nome]" na conversação
• Gemini CLI: Use o comando gemini prompt [nome]

Categorias de Prompts

Os prompts estão organizados em duas categorias para diferentes perfis de usuário:

Categoria	Público-Alvo	Foco	Quantidade
Gestores	Gerentes, Diretores, CIOs	Dashboards executivos, relatórios estratégicos, compliance, custos	7 prompts
Analistas	Técnicos, Admins, DevOps	Troubleshooting, operações práticas, guias de restore	8 prompts

---

🎯 Prompts para Gestores (7)

Foco em visão estratégica, compliance e relatórios executivos (formato compacto, ideal para WhatsApp/Teams).

Prompt	Descrição	Argumentos
veeam_backup_health_summary	Resumo executivo de saúde dos backups com taxa de sucesso e alertas críticos	period_days (opcional, padrão 7)
veeam_storage_growth_forecast	Previsão de crescimento de storage com projeção de capacidade	forecast_months (opcional, padrão 3)
veeam_backup_cost_analysis	Análise de custo de backup por cliente com otimizações recomendadas	client_name (opcional)
veeam_recovery_sla_compliance	Compliance de RTO/RPO e aderência aos SLAs de recuperação	period_days (opcional, padrão 30)
veeam_backup_success_rate	Taxa de sucesso de backups por job com tendências e alertas	period_days (opcional, padrão 7)
veeam_repository_capacity	Capacidade de repositórios com alertas de espaço e previsão de esgotamento	threshold_percent (opcional, padrão 80)
veeam_vm_protection_coverage	Cobertura de proteção de VMs, identificando VMs não protegidas	client_name (opcional)

🔧 Prompts para Analistas Técnicos (8)

Foco em troubleshooting, operações práticas e guias de restore.

Prompt	Descrição	Argumentos
veeam_failed_job_investigation	Investigação detalhada de job falhado com logs e troubleshooting	job_id (obrigatório)
veeam_restore_point_lookup	Busca de restore points disponíveis para uma VM específica	vm_name (obrigatório)
veeam_restore_guide	Guia passo-a-passo para restauração de VM/arquivo	vm_name (obrigatório), restore_type (opcional)
veeam_backup_validation	Validação de integridade de backup com teste de restore	vm_name (obrigatório)
veeam_vm_backup_history	Histórico completo de backups de uma VM com estatísticas de performance	vm_name (obrigatório), period_days (opcional)
veeam_repository_space_alert	Alerta de espaço em repositório com análise de crescimento	repository_name (obrigatório)
veeam_job_status	Status rápido de jobs de backup com última execução e próxima janela	job_name (opcional)
veeam_tape_job_status	Status de jobs de fita com última gravação e mídia utilizada	tape_job_name (opcional)

💡 Cada prompt inclui uma linha 🛠️ Ferramentas que indica quais tools acionar (ex.: groupByJob=true para saúde, busca por nome de VM, get_log por VM), guiando o assistente ao caminho mais eficiente.

Como descobrir e executar (via MCPHub):

• veeam_list_mcp_prompts — lista os 15 prompts com seus argumentos
• veeam_get_mcp_prompt — executa um prompt pelo name (+ objeto arguments). Argumentos obrigatórios ausentes retornam um erro claro em pt-BR (ex.: falta job_id).

# Exemplo: investigar um job que falhou
curl -X POST http://localhost:8825/mcp \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"veeam_get_mcp_prompt","arguments":{"name":"veeam_failed_job_investigation","arguments":{"job_id":"BKP-JOB-LOCAL-..."}}},"id":1}'

---

🔌 Integração com IDEs

Claude Desktop (Modo MCP stdio)

Adicione ao 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

{
  "mcpServers": {
    "veeam-backup": {
      "command": "node",
      "args": [
        "/opt/mcp-servers/veeam-backup/vbr-mcp-server.js",
        "--mcp"
      ]
    }
  }
}

Importante:

• Use caminho absoluto para o arquivo .js
• Use flag --mcp para modo stdio
• Reinicie o Claude Desktop após configurar

---

Claude Code (Modo HTTP Streamable) ⭐

Adicione ao .mcp.json no workspace ou ~/.claude/settings.json:

{
  "mcpServers": {
    "veeam-backup": {
      "type": "streamable-http",
      "url": "http://localhost:8825/mcp",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN_AQUI"
      }
    }
  }
}

Recursos:

• ✅ Protocolo MCP 2024-11-05 (JSON-RPC 2.0)
• ✅ Autenticação Bearer Token obrigatória
• ✅ Session management com UUID
• ✅ 15 ferramentas disponíveis

Endpoints Implementados:

• POST /mcp - Handler JSON-RPC principal (initialize, tools/list, tools/call)
• GET /mcp - Server-Sent Events para notificações
• DELETE /mcp - Terminação de sessão graceful
• GET /health - Health check com info de autenticação

---

Gemini CLI (Modo HTTP) ⭐

Adicione ao ~/.gemini/settings.json:

{
  "mcpServers": {
    "veeam-backup": {
      "httpUrl": "http://localhost:8825/mcp",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN_AQUI"
      },
      "timeout": 30000
    }
  }
}

Diferenças de Configuração:

• Claude Code: Usa propriedade url
• Gemini CLI: Usa propriedade httpUrl
• Ambos: Requerem header Authorization: Bearer TOKEN

---

Copilot Studio (OpenAPI)

Configure os endpoints individuais:

• Base URL: http://localhost:8825
• Endpoints:
  • POST /backup-jobs
  • POST /backup-sessions
  • POST /job-details
  • POST /backup-proxies
  • POST /backup-repositories
  • POST /license-info
  • POST /server-info

OpenAPI Spec: Importe de http://localhost:8825/openapi.json

---

💼 Exemplos Práticos

Exemplo 1: Monitorar Jobs com Falha

Pergunta ao Claude:

"Mostre todos os jobs de backup que falharam nas últimas 24 horas"

Processo:

1. Claude chama veeam_search_backup_sessions com statusFilter="Failed" e hours=24
2. Recebe resultado já filtrado e formatado em Markdown
3. Apresenta tabela com jobs falhados

Resposta Esperada:

Encontrei 2 jobs com falha nas últimas 24 horas:

1. Job: SQL-Backup-Daily
   Status: Failed
   Horário: 2024-12-09 03:30
   Erro: "Network timeout during backup"

2. Job: Exchange-Full-Weekly
   Status: Failed
   Horário: 2024-12-09 01:15
   Erro: "Insufficient disk space in repository"

---

Exemplo 2: Verificar Capacidade de Repositórios

Pergunta ao Claude:

"Quais repositórios estão com mais de 80% de uso?"

Processo:

1. Claude chama veeam_search_infrastructure com type="repositories"
2. Calcula percentual de uso
3. Filtra repositórios >80%
4. Alerta sobre espaço crítico

Resposta Esperada:

⚠️ Atenção: 2 repositórios com uso crítico:

1. Repository: REPO-PRODUCTION
   Capacidade: 10 TB
   Usado: 8.5 TB (85%)
   Livre: 1.5 TB
   Recomendação: Considerar expansão em breve

2. Repository: REPO-ARCHIVE
   Capacidade: 5 TB
   Usado: 4.2 TB (84%)
   Livre: 800 GB
   Recomendação: Mover dados antigos ou expandir

---

Exemplo 3: Análise de Performance de Job

Pergunta ao Claude:

"Me mostre o histórico de performance do job 'VM-Production-Backup' nos últimos 7 dias"

Processo:

1. Claude chama veeam_manage_backup_jobs com action="get_details" e jobId
2. Analisa últimas sessões
3. Calcula médias de duração e throughput
4. Identifica tendências

Resposta Esperada:

Análise de Performance: VM-Production-Backup (últimos 7 dias)

Estatísticas:
• Execuções: 7
• Taxa de sucesso: 100%
• Duração média: 2h 15min
• Throughput médio: 450 GB/hora
• Dados processados (média): 1.2 TB por execução

Tendência:
✅ Duração estável (variação <10%)
✅ Taxa de transferência consistente
⚠️ Última execução 15min mais lenta (investigar)

Próxima execução: Hoje às 23:00

---

Exemplo 4: Verificar Status de Licença

Pergunta ao Claude:

"Minha licença Veeam está próxima de vencer?"

Processo:

1. Claude chama veeam_get_license_compliance
2. Obtém data de expiração
3. Calcula dias restantes
4. Alerta se <30 dias

Resposta Esperada:

Status da Licença Veeam:

Tipo: Veeam Backup & Replication Enterprise Plus
Licenças: 50 (48 em uso, 2 disponíveis)
Expiração: 2025-06-15
Dias restantes: 188 dias
Status de suporte: Ativo

✅ Sua licença está válida e com suporte ativo.
📅 Recomendação: Iniciar renovação 30 dias antes (15/05/2025).

---

🔒 Segurança

Autenticação Automática

Este servidor implementa autenticação automática transparente:

1. Middleware de Autenticação: Gerencia tokens automaticamente
2. Token Caching: Cache de 55 minutos (evita re-autenticações desnecessárias)
3. Promise Memoization: Previne race conditions em requisições concorrentes
4. Refresh Automático: Renova token quando próximo de expirar

Benefícios:

• ✅ Zero configuração manual de autenticação
• ✅ Ferramentas não precisam gerenciar tokens
• ✅ Performance otimizada (menos chamadas de auth)
• ✅ Thread-safe para requisições paralelas

SSL/TLS

Desenvolvimento (padrão):

VEEAM_IGNORE_SSL=true

Produção (recomendado):

VEEAM_IGNORE_SSL=false

Para ambientes de produção:

1. Instale certificados SSL válidos no Veeam VBR
2. Configure VEEAM_IGNORE_SSL=false
3. Valide certificados com openssl s_client

Controle de Acesso

Recomendações:

1. Firewall: Restrinja porta 8825 apenas a IPs confiáveis

   # Exemplo UFW (Linux)
   ufw allow from 203.0.113.0/24 to any port 8825
   

2. Reverse Proxy: Use Nginx/Apache com autenticação

   # Exemplo Nginx com Basic Auth
   location / {
       auth_basic "Veeam MCP Server";
       auth_basic_user_file /etc/nginx/.htpasswd;
       proxy_pass http://localhost:8825;
   }
   

3. VPN/Zerotrust: Acesso via VPN corporativa ou solução Zerotrust

Princípio do Menor Privilégio

Crie conta de serviço com apenas permissões de leitura:

1. Acesse Veeam Console
2. Crie usuário svc-mcp-reader
3. Atribua role Veeam Restore Operator (read-only)
4. Use este usuário no .env

VEEAM_USERNAME=.\\svc-mcp-reader
VEEAM_PASSWORD=ReadOnlyP@ssw0rd2024

---

🤝 Contribuindo

Contribuições são bem-vindas! Este projeto segue as práticas de desenvolvimento da Skills IT.

Processo de Contribuição

1. Fork o repositório
2. Clone seu fork localmente
3. Crie branch para sua feature: git checkout -b feat/nova-feature
4. Desenvolva seguindo as convenções do projeto
5. Teste localmente todas as mudanças
6. Commit seguindo Conventional Commits (português-BR):

   git commit -m "feat(tools): adicionar ferramenta de restore points"
   git commit -m "fix(auth): corrigir timeout em token refresh"
   git commit -m "docs(readme): atualizar exemplos de uso"
   

7. Push para seu fork: git push origin feat/nova-feature
8. Abra Pull Request com descrição detalhada

Conventional Commits (PT-BR)

Tipo	Descrição	Exemplo
feat	Nova funcionalidade	feat(tools): adicionar backup-repository-tool
fix	Correção de bug	fix(auth): corrigir race condition em token cache
docs	Documentação	docs(readme): adicionar seção de troubleshooting
refactor	Refatoração de código	refactor(auth): simplificar lógica de middleware
test	Testes	test(tools): adicionar testes para job-details-tool
chore	Manutenção	chore(deps): atualizar dependências

Diretrizes de Código

• Idioma: Variáveis/funções em inglês, comentários em português-BR
• Formatação: Prettier com 2 espaços de indentação
• Lint: ESLint configurado no projeto
• Commits: Mensagens claras e descritivas em português-BR

---

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

Resumo:

• ✅ Uso comercial permitido
• ✅ Modificação permitida
• ✅ Distribuição permitida
• ✅ Uso privado permitido
• ⚠️ Sem garantias (AS-IS)

---

🎖️ Créditos

Desenvolvido por

Skills IT - Soluções em Tecnologia 🇧🇷

• Website: https://skillsit.com.br
• Email: [email protected]
• LinkedIn: Skills IT

Inspirado por

• Model Context Protocol (MCP) - Anthropic
• Jorge de la Cruz - Veeam MCP Original
• Veeam Software - REST API Documentation

Tecnologias Utilizadas

• Node.js 20+ - Runtime JavaScript
• Express.js - Framework HTTP
• @modelcontextprotocol/sdk - SDK oficial MCP
• Swagger UI - Documentação interativa OpenAPI
• Docker - Containerização

---

📞 Suporte

Precisa de Ajuda?

1. GitHub Issues: Abrir Issue
2. Email: [email protected]
3. Documentação Adicional:
   • ARCHITECTURE_AND_DESIGN.md - Detalhes técnicos de arquitetura
   • DEPLOYMENT.md - Guia completo de deploy
   • SECURITY.md - Guia de segurança
   • CONTRIBUTING.md - Guia de contribuição

Problemas Comuns

Consulte a seção de Troubleshooting para soluções de problemas comuns.

---