nmap MCP server for AI-assisted network security auditing
by @sbmilburn
Network scanning MCP server wrapping nmap. Provides 14 purpose-built tools for host discovery, port scanning (SYN/TCP/UDP), service & OS detection, NSE scrip...
clawhub install nmap-mcpπ About This Skill
name: nmap-mcp description: > Network scanning MCP server wrapping nmap. Provides 14 purpose-built tools for host discovery, port scanning (SYN/TCP/UDP), service & OS detection, NSE script execution, and vulnerability scanning. Returns structured JSON output. Includes scope enforcement (CIDR allowlist), audit logging, and scan persistence. Use when performing network security audits, asset discovery, or recon on authorized networks.
nmap-mcp Skill
MCP server that exposes nmap as structured tools with scope enforcement, audit logging, and persistent scan results.
Prerequisites
/usr/bin/nmap or configure path in config.yaml)fastmcp, python-nmap, pyyamlcap_net_raw capability on the nmap binary (see Setup)Setup
# 1. Install Python dependencies
pip install fastmcp python-nmap pyyaml2. Grant nmap raw socket capability (required for SYN + OS detection)
Only needs to be done once. Re-run after nmap upgrades.
sudo setcap cap_net_raw+ep $(which nmap)3. Verify it worked
getcap $(which nmap)
Expected: /usr/bin/nmap cap_net_raw=ep
4. Configure scope (edit config.yaml β set your allowed CIDRs)
5. Register with mcporter (see mcporter.json entry below)
mcporter.json Entry
{
"nmap": {
"command": "python3",
"args": ["-u", "/path/to/nmap-mcp/server.py"],
"type": "stdio",
"env": {
"NMAP_CONFIG": "/path/to/nmap-mcp/config.yaml"
}
}
}
Configuration (config.yaml)
# Scope enforcement β targets outside these CIDRs are rejected
allowed_cidrs:
- "127.0.0.0/8"
- "192.168.1.0/24" # your local networkPaths (defaults to relative paths if omitted)
audit_log: "./audit.log"
scan_dir: "./scans"
nmap_bin: "/usr/bin/nmap"Timeouts in seconds
timeouts:
quick: 120
standard: 300
deep: 600
Tools
| Tool | Purpose | Privileges |
|------|---------|-----------|
| nmap_ping_scan | ICMP+TCP host discovery | none |
| nmap_arp_discovery | ARP host discovery (LAN) | cap_net_raw |
| nmap_top_ports | Fast scan of N common ports | none |
| nmap_syn_scan | SYN half-open port scan | cap_net_raw |
| nmap_tcp_scan | Full TCP connect port scan | none |
| nmap_udp_scan | UDP port scan | cap_net_raw |
| nmap_service_detection | Service/version detection | none |
| nmap_os_detection | OS fingerprinting | cap_net_raw |
| nmap_script_scan | Run named NSE scripts | none |
| nmap_vuln_scan | Run vuln NSE category | none |
| nmap_full_recon | SYN+service+OS+scripts | cap_net_raw |
| nmap_custom_scan | Arbitrary flags (scoped+logged) | varies |
| nmap_list_scans | List recent saved scans | none |
| nmap_get_scan | Retrieve scan by ID | none |
Running Tests
python3 -m pytest tests/ -v
28 tests covering scope enforcement, audit logging,
scan persistence, injection guards, and live scans
βοΈ Configuration
# 1. Install Python dependencies
pip install fastmcp python-nmap pyyaml2. Grant nmap raw socket capability (required for SYN + OS detection)
Only needs to be done once. Re-run after nmap upgrades.
sudo setcap cap_net_raw+ep $(which nmap)3. Verify it worked
getcap $(which nmap)
Expected: /usr/bin/nmap cap_net_raw=ep
4. Configure scope (edit config.yaml β set your allowed CIDRs)
5. Register with mcporter (see mcporter.json entry below)