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

Running Tests

python3 -m pytest tests/ -v
# 28 tests covering scope enforcement, audit logging,
# scan persistence, injection guards, and live scans