MCP server that exposes nmap as tools an LLM agent can call — with mandatory scope enforcement so you can't point an agent at an unauthorized host by accident.
This is a thin, responsible wrapper: every scan target is checked against an allowlist before nmap is ever invoked. No allowlist → every scan is refused with a clear error. This is the only way I'm comfortable publishing an MCP server that shells out to a scanner.
npm installRequires Node.js ≥ 22.5 and nmap on PATH. On macOS: brew install nmap.
Set MCP_NMAP_SCOPE to a comma-separated list of authorized targets. Supported forms:
- IPv4 CIDR:
10.0.0.0/8 - IPv4 single host:
203.0.113.5(treated as/32) - Hostname:
scanme.nmap.org - Wildcard hostname:
*.example.internal
# Legal-to-scan example
export MCP_NMAP_SCOPE="scanme.nmap.org,10.0.0.0/8"
node src/index.jsIf MCP_NMAP_SCOPE is unset, every scan is refused. This is intentional.
{
"mcpServers": {
"nmap": {
"command": "node",
"args": ["/absolute/path/to/mcp-nmap/src/index.js"],
"env": { "MCP_NMAP_SCOPE": "scanme.nmap.org,10.0.0.0/8" }
}
}
}| Tool | Purpose |
|---|---|
scan_ports |
TCP port scan (-sS if root, -sT otherwise). Options: ports, timing. |
service_detect |
Version detection on specific ports (-sV). |
ping_sweep |
Host discovery across a CIDR (-sn). |
check_scope |
Return whether a target is in scope, without running a scan. Useful for the agent to plan before acting. |
All tools return structured JSON parsed from nmap's XML output.
- Scope enforcement runs before spawning nmap. Out-of-scope targets never touch the binary.
- No raw-args passthrough. The server builds the argv itself from typed options. You can't shell-inject via a target name.
- Timeouts. Every scan has a hard timeout (default 120s, configurable per tool).
- No destructive flags.
--script,-O,--traceroute, etc. are not exposed. Add them deliberately tosrc/nmap.jsif you need them.
Only scan hosts you own or have explicit written permission to test. Unauthorized scanning is illegal in most jurisdictions. The scope allowlist helps you configure what you have permission to hit; it cannot verify your authority to scan. That is on you.
MIT — see LICENSE.