nmap-mcp 0.1.0

Nmap network scanner and NSE scripting engine control for AI assistants via MCP
nmap-mcp-0.1.0 is not a library.

nmap-mcp — Network scanning for AI assistants

license github

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 — -sV version probing with CPE identifiers, and -O fingerprinting.
  • 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:

[mcp_servers.nmap-mcp]
command = "nmap-mcp"
enabled = 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 to nmap on PATH. 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's script.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:

{ "mcpServers": { "nmap-mcp": { "command": "nmap-mcp" } } }

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_BIN then PATH), 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's script.db (one Entry { ... } per line) with category filtering and per-category counts.
  • script_help — parser for nmap --script-help output 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-help fixtures, 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 on NMAP_MCP_BIN pointing at a real nmap) run the server against a real nmap scanning 127.0.0.1, including a self-contained local HTTP server for the http-title script.
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.sh from the repo root produces bin/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.