nmap-mcp Skill

MCP server that exposes nmap as structured tools with scope enforcement,

audit logging, and persistent scan results.

Prerequisites

• nmap installed (/usr/bin/nmap or configure path in config.yaml)
• Python 3.10+ with fastmcp, python-nmap, pyyaml
• For SYN/OS/ARP scans: cap_net_raw capability on the nmap binary (see Setup)

Setup

# 1. Install Python dependencies
pip install fastmcp python-nmap pyyaml

# 2. 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 network

# Paths (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