NmapMCP

NmapMCP

Um servidor MCP (Model Context Protocol) Nmap de nível de produção — não um wrapper simples.

A maioria dos servidores MCP Nmap envia a saída do nmap diretamente para uma IA como texto bruto e pronto. O NmapMCP analisa a saída XML do nmap em JSON estruturado, oferece 35 ferramentas especializadas em vez de um único nmap_scan genérico, e adiciona as proteções de segurança que uma ferramenta que executa varreduras de rede arbitrárias realmente precisa.

⚠️ Apenas para uso educacional. Varredura apenas hosts e redes que você possui ou tem autorização explícita para testar. Consulte Uso Responsável abaixo.

---

Por que este é diferente

Saída estruturada, não texto bruto. A saída XML do nmap é totalmente analisada em JSON limpo — impressões digitais de SO, consultas de fornecedor MAC, strings CPE, resultados de scripts NSE por porta, saltos de traceroute, tempo de atividade — para que um assistente de IA possa raciocinar sobre campos em vez de usar regex em uma parede de stdout.

35 ferramentas especializadas, não uma varredura genérica. Em vez de forçar a IA a lembrar nomes corretos de scripts NSE e combinações de flags, há uma ferramenta específica por caso de uso: ssl_scan, smb_vuln_scan, database_scan, dns_enum, rdp_scan, ftp_scan, ssh_audit, e mais — cada uma pré-configurada com os scripts e flags corretos.

Histórico de varreduras e comparação. list_scan_history, get_scan_result, e diff_scans permitem executar uma varredura, executá-la novamente mais tarde e perguntar "o que mudou?" — produzindo uma comparação estruturada de portas que abriram, fecharam ou mudaram de versão. A maioria dos servidores MCP Nmap não rastreia histórico.

Proteções de segurança incorporadas.

• Lista de permissões de flags — cada flag do nmap é verificada contra uma lista de permissões explícita antes de chegar ao shell; nada arbitrário passa
• Validação de alvos — entrada verificada por regex e com limite de comprimento
• Proteção de faixa privada — IPs públicos são bloqueados por padrão; escaneá-los requer definir explicitamente NMAP_ALLOW_PUBLIC=1
• Limitação de concorrência — um semáforo limita varreduras paralelas a 3, para que uma IA não sature acidentalmente a rede com varreduras simultâneas de todas as portas
• Tempo limite rígido — toda varredura é encerrada após 1800s se travar

Inventário de rede em duas fases. network_inventory executa primeiro uma varredura de ping e depois executa detecção de serviços apenas contra hosts que responderam — muito mais eficiente do que lançar cegamente uma varredura de serviços em um /24 inteiro.

Resumos legíveis por humanos. get_host_summary retorna um relatório de texto formatado (hostname, palpite de SO, portas abertas, destaques de scripts, traceroute) projetado para ser lido diretamente por uma pessoa, não apenas analisado por um modelo.

---

Referência de ferramentas

Categoria	Ferramentas
Varredura geral	nmap_scan, structured_scan, quick_scan, top_ports_scan, full_port_scan, check_single_port
Descoberta de hosts	ping_sweep, arp_scan, network_inventory
Técnicas de varredura	syn_stealth_scan, udp_scan, ipv6_scan
Serviços / SO	service_scan, os_detection, aggressive_scan, banner_grab
Vulnerabilidades	vuln_scan, safe_vuln_scan, smb_vuln_scan
Auditorias de protocolo	ssl_scan, http_enum, dns_enum, smb_enum, ftp_scan, ssh_audit, rdp_scan, database_scan
Análise de rede	firewall_detection, traceroute_scan
Scripts	script_scan (executa qualquer script/categoria NSE pelo nome)
Histórico e relatórios	list_scan, list_scan_history, get_scan_result, diff_scans, get_host_summary

Exemplos de prompts uma vez conectado ao Claude:

run a quick_scan on 192.168.1.100
get_host_summary on 192.168.1.1
run a vuln_scan on 192.168.1.50
network_inventory of 192.168.1.0/24
diff_scans between scan_id_a and scan_id_b

---

Configuração

Requisitos

Requisito	Versão	Notas
Python	3.13+
Nmap	7.9+	O binário real do scanner
uv	Mais recente	Gerenciador de pacotes Python
Claude Desktop	Mais recente	Ou qualquer cliente compatível com MCP

1. Instale Python 3.13+

Baixe de python.org. No Windows, marque "Add Python to PATH" durante a instalação. Verifique:

python --version

2. Instale Nmap

Baixe de nmap.org. Mantenha Npcap marcado durante a instalação (Windows). Verifique:

nmap --version

3. Instale uv

pip install uv

4. Obtenha o projeto

git clone https://github.com/<your-username>/NmapMCP.git
cd NmapMCP

5. Aponte o servidor para o seu binário Nmap

Por padrão, o servidor procura Nmap via a variável de ambiente NMAP_PATH (com fallback para um padrão do Windows). Defina-a para o caminho real do seu nmap — no macOS/Linux geralmente é apenas nmap ou /usr/bin/nmap; no Windows, precisa do caminho curto 8.3 com barras normais, ex.: C:/PROGRA~1/Nmap/nmap.exe (encontre o seu com where nmap, depois converta para caminho curto se contiver espaços).

Defina-a como uma variável de ambiente em vez de editar o código-fonte:

export NMAP_PATH=/usr/bin/nmap   # macOS/Linux
set NMAP_PATH=C:/PROGRA~1/Nmap/nmap.exe   # Windows

6. Instale as dependências

uv venv
uv pip install -e .

7. Configure seu cliente MCP

Adicione à configuração do seu Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json no Windows, ~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
  "mcpServers": {
    "NmapMCP": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/NmapMCP", "run", "main.py"]
    }
  }
}

Reinicie o Claude Desktop e procure o ícone de ferramentas para confirmar que carregou.

Docker

Um Dockerfile está incluído para implantação em contêiner; veja-o para detalhes.

---

Uso Responsável

Este projeto é publicado apenas para fins educacionais e de testes autorizados. Ferramentas de varredura de rede como Nmap podem ser mal utilizadas para sondar sistemas sem autorização, o que é ilegal na maioria das jurisdições.

• Execute varreduras apenas contra hosts, redes ou serviços que você possui ou para os quais tem permissão escrita explícita para testar
• A varredura de IPs públicos está desabilitada por padrão (NMAP_ALLOW_PUBLIC=1 necessário para substituir) — deixe desativado a menos que precise especificamente e tenha autorização
• O(s) mantenedor(es) deste repositório não são responsáveis por uso indevido

---

Solução de problemas

"nmap not found" — Confirme que nmap --version funciona no seu terminal e que NMAP_PATH aponta para o binário correto.

"0 hosts up" em tudo (Windows) — Geralmente é um problema de permissões do Npcap. Use quick_scan ou get_host_summary (baseado em conexão TCP, sem necessidade de admin) em vez de ping_sweep/arp_scan, ou execute seu terminal/Claude Desktop como Administrador.

O ícone de ferramentas não aparece no Claude Desktop — Valide seu JSON de configuração, confirme que o caminho está correto e absoluto, depois feche e reabra completamente o Claude Desktop.

Algumas varreduras precisam de privilégios elevados — syn_stealth_scan, udp_scan, arp_scan, e os_detection geralmente exigem admin/root.

---

Roadmap / Limitações conhecidas

Sendo transparente sobre onde isso está:

• Sem suíte de testes automatizados ainda
• Arquitetura de arquivo único (main.py) — funciona bem, mas uma futura divisão em módulos runner/parser/validator/tools melhoraria a manutenibilidade
• O histórico de varreduras é apenas em memória e não persiste entre reinicializações; sem log de auditoria persistente ainda
• Sem limite de taxa por alvo (apenas o paralelismo global é limitado)

---

Licença

MIT — veja LICENSE.