A production-grade Nmap MCP (Model Context Protocol) server — not a thin wrapper.
Most Nmap MCP servers pipe nmap output straight to an AI as raw text and call it done. NmapMCP parses nmap's XML output into structured JSON, ships 35 purpose-built tools instead of one generic nmap_scan, and adds the safety rails a tool that runs arbitrary network scans actually needs.
⚠️ Educational use only. Only scan hosts and networks you own or are explicitly authorized to test. See Responsible Use below.
Structured output, not raw text. nmap's XML output is fully parsed into clean JSON — OS fingerprints, MAC vendor lookups, CPE strings, per-port NSE script results, traceroute hops, uptime — so an AI assistant can reason over fields instead of regex-ing a wall of stdout.
35 specialized tools, not one generic scan.
Instead of forcing the AI to remember correct NSE script names and flag combos, there's a purpose-built tool per use case: ssl_scan, smb_vuln_scan, database_scan, dns_enum, rdp_scan, ftp_scan, ssh_audit, and more — each pre-configured with the right scripts and flags.
Scan history and diffing.
list_scan_history, get_scan_result, and diff_scans let you run a scan, run it again later, and ask "what changed?" — producing a structured diff of ports that opened, closed, or changed version. Most Nmap MCP servers don't track history at all.
Security guardrails baked in.
- Flag allowlist — every nmap flag is checked against an explicit allowlist before it reaches the shell; nothing arbitrary gets through
- Target validation — regex-checked, length-capped input
- Private-range guard — public IPs are blocked by default; scanning them requires explicitly setting
NMAP_ALLOW_PUBLIC=1 - Concurrency limiting — a semaphore caps parallel scans at 3, so an AI can't accidentally saturate the network with simultaneous full-port scans
- Hard timeout — every scan is killed after 1800s if it hangs
Two-phase network inventory.
network_inventory runs a ping sweep first, then only runs service detection against hosts that responded — far more efficient than blindly throwing a service scan at an entire /24.
Human-readable summaries.
get_host_summary returns a formatted text report (hostname, OS guess, open ports, script highlights, traceroute) designed to be read directly by a person, not just parsed by a model.
| Category | Tools |
|---|---|
| General scanning | nmap_scan, structured_scan, quick_scan, top_ports_scan, full_port_scan, check_single_port |
| Host discovery | ping_sweep, arp_scan, network_inventory |
| Scan techniques | syn_stealth_scan, udp_scan, ipv6_scan |
| Service / OS | service_scan, os_detection, aggressive_scan, banner_grab |
| Vulnerability | vuln_scan, safe_vuln_scan, smb_vuln_scan |
| Protocol audits | ssl_scan, http_enum, dns_enum, smb_enum, ftp_scan, ssh_audit, rdp_scan, database_scan |
| Network analysis | firewall_detection, traceroute_scan |
| Scripting | script_scan (run any NSE script/category by name) |
| History & reporting | list_scan, list_scan_history, get_scan_result, diff_scans, get_host_summary |
Example prompts once connected to 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
| Requirement | Version | Notes |
|---|---|---|
| Python | 3.13+ | |
| Nmap | 7.9+ | The actual scanner binary |
| uv | Latest | Python package manager |
| Claude Desktop | Latest | Or any MCP-compatible client |
Download from python.org. On Windows, check "Add Python to PATH" during install. Verify:
python --version
Download from nmap.org. Keep Npcap checked during install (Windows). Verify:
nmap --version
pip install uv
git clone https://github.com/<your-username>/NmapMCP.git
cd NmapMCP
By default the server looks for Nmap via the NMAP_PATH environment variable (falls back to a Windows default). Set it to your actual nmap path — on macOS/Linux this is usually just nmap or /usr/bin/nmap; on Windows it needs the 8.3 short path with forward slashes, e.g. C:/PROGRA~1/Nmap/nmap.exe (find yours with where nmap, then convert to short path if it contains spaces).
Set it as an environment variable rather than editing the source:
export NMAP_PATH=/usr/bin/nmap # macOS/Linux
set NMAP_PATH=C:/PROGRA~1/Nmap/nmap.exe # Windows
uv venv
uv pip install -e .
Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"NmapMCP": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/NmapMCP", "run", "main.py"]
}
}
}Restart Claude Desktop and look for the tools icon to confirm it loaded.
A Dockerfile is included for containerized deployment; see it for details.
This project is published for educational and authorized-testing purposes only. Network scanning tools like Nmap can be misused to probe systems without authorization, which is illegal in most jurisdictions.
- Only run scans against hosts, networks, or services you own or have explicit written permission to test
- Public-IP scanning is disabled by default (
NMAP_ALLOW_PUBLIC=1required to override) — leave this off unless you specifically need it and have authorization - The maintainer(s) of this repository are not responsible for misuse
"nmap not found" — Confirm nmap --version works in your terminal, and that NMAP_PATH points to the correct binary.
"0 hosts up" on everything (Windows) — Usually a Npcap permissions issue. Use quick_scan or get_host_summary (TCP-connect based, no admin needed) instead of ping_sweep/arp_scan, or run your terminal/Claude Desktop as Administrator.
Tools icon doesn't appear in Claude Desktop — Validate your config JSON, confirm the path is correct and absolute, then fully quit and reopen Claude Desktop.
Some scans need elevated privileges — syn_stealth_scan, udp_scan, arp_scan, and os_detection typically require admin/root.
Being transparent about where this stands:
- No automated test suite yet
- Single-file architecture (
main.py) — works well, but a future split into runner/parser/validator/tools modules would improve maintainability - Scan history is in-memory only and does not persist across restarts; no persistent audit log yet
- No per-target rate limiting (only global parallelism is capped)
MIT — see LICENSE.