nmap-mcp — Network scanning for AI assistants
An MCP server that turns the nmap network scanner and its
Nmap Scripting Engine (NSE) into tools an AI assistant can drive over MCP
stdio. The server executes the real nmap binary, requests -oX - XML output,
and parses it into structured JSON — no HTML scraping, no reimplementation of
nmap's scanning logic.
The server covers the full scan lifecycle plus the NSE scripting engine:
- Environment check — nmap version, binary path, script database location, and the installed NSE script inventory with per-category counts.
- Script discovery — list the NSE scripts shipped with the installation,
filtered by category (
default,safe,vuln,brute, ...) and name; fetch a script's full description, categories, and nsedoc URL via--script-help. - Host discovery — ping sweeps (
-sn) over a host, CIDR, or list. - Port scanning — TCP connect scans (
-sT, no root needed) with explicit port lists, ranges, service names, or--top-ports. - Service and OS detection —
-sVversion probing with CPE identifiers, and-Ofingerprinting. - NSE script execution — run scripts or whole categories against a target
with
--script-args, and read their structured output exactly as the NSE API serializes it (keyed entries become objects, unkeyed entries arrays). - Full scans — one deep pass with default scripts plus version and OS
detection (
-sT -sV -O -sC).
All commands are spawned with explicit argument arrays — never through a
shell — so a target like 1.2.3.4; rm -rf / is inert data, not a command.
Every scan is bounded by a configurable timeout, and results are returned as
pretty-printed JSON that any MCP client (Open Grok, Claude, Codex) can read.
Installation
Requires a Rust toolchain (rust-version 1.88) and nmap on the machine. nmap
must be reachable as nmap on PATH, or pointed at with the NMAP_MCP_BIN
environment variable:
cargo install nmap-mcp
or install directly from the repository:
cargo install --git https://github.com/JLFN/nmap-mcp
The binary speaks MCP over stdio; no network listener is opened.
Configuration
Open Grok
Add the server to ~/.opengrok/config.toml:
[]
= "nmap-mcp"
= true
Refresh the MCP list with /mcps (press r) or restart. The repository
ships an Open Grok skill at skills/nmap-mcp/SKILL.md that teaches the agent
when and how to use each tool.
Environment variables
NMAP_MCP_BIN— path to the nmap executable. Defaults tonmaponPATH. Point this at a specific install (for example a locally extracted nmap) when nmap is not on the default path.NMAP_MCP_SCRIPT_DB— path to nmap'sscript.db. Defaults to walking up from the nmap binary and the standard system locations.
Other MCP clients
Any MCP-capable client can launch the binary directly, for example:
Architecture
The server is a Rust binary built on rmcp 3.1 with the standard stdio
transport. Tool calls are handled by a tool router; each tool validates its
input, builds an nmap argument vector, runs the binary, and parses the
result. The pipeline is split into small, purely testable modules:
nmap_runner— binary discovery (NMAP_MCP_BINthenPATH), process spawning with explicit argument arrays, timeout enforcement, and the-oX -scan helper.nmap_xml— streaming parser for nmap's XML output: hosts, ports, service and OS matches, traceroute, uptime, runstats, and the nested<table>/<elem>structure of NSE script output.script_db— parser for nmap'sscript.db(oneEntry { ... }per line) with category filtering and per-category counts.script_help— parser fornmap --script-helpoutput into structured script metadata, including not-found diagnostics.validate— target, port, timing, and timeout validation that rejects malformed input with clear messages.
Testing
The test suite runs without root and without scanning anything real:
- Unit tests (25) cover every parser against realistic nmap XML, script.db,
and
--script-helpfixtures, plus input validation. - Wire-protocol tests (14) spawn the real compiled binary and speak MCP over
stdio exactly like a client: handshake,
tools/list(all nine tools advertised with descriptions and schemas), a tool call per scan type against a fake nmap shim, error paths (empty targets, out-of-range ports, injection attempts), unknown-tool JSON-RPC errors, and multi-call stability. - Live tests (3,
#[ignore], gated onNMAP_MCP_BINpointing at a real nmap) run the server against a real nmap scanning127.0.0.1, including a self-contained local HTTP server for thehttp-titlescript.
cargo test
cargo test --test live -- --ignored # with NMAP_MCP_BIN set to a real nmap
Live test
On this machine, nmap 7.95 runs from a userspace extraction (no root):
LD_LIBRARY_PATH=/data/nmap-local/usr/lib/x86_64-linux-gnu \
NMAP_MCP_BIN=/data/nmap-local/usr/bin/nmap \
cargo test --test live -- --ignored
The live suite verifies a real nmap_status (610 scripts), a ping sweep and
port scan of localhost (port 22 open), and an http-title script scan
against a test HTTP server the suite starts itself.
Project layout
src/— server (main.rs) and the four parser/runner modules.tests/— wire-protocol tests, live tests, and fixtures (fake nmap shim and script.db).skills/nmap-mcp/— the Open Grok skill.docs/— setup and verification guides.build/— embedded copy of the standard builder (bash build/linux/build.shfrom the repo root producesbin/nmap-mcp).
Documentation
- docs/setup.md — installing nmap, building, and wiring the server into Open Grok.
- docs/verification.md — how the test suites work and how to verify a release build.
Known limitations
- OS detection (
-O) and SYN scans need raw sockets, which usually means root; as an unprivileged user use connect scans (-sT, the default here). nmap itself reports the limitation when it cannot fingerprint. - Scanning is active network reconnaissance and is detectable by the target. Scan only hosts the user has authorized.
- The server talks to the nmap binary's documented CLI and XML output; it does not embed nmap, so nmap must be installed on the machine running the server.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.