nmap

nmap-mcp exposes six scanning tools that wrap Nmap for AI-driven network assessment within MCP workflows. The tools include discover-hosts for host discovery, quick-scan for rapid port surveying, scan-ports for configurable port scanning across multiple scan types and timing templates, detect-services to identify service versions, detect-os for OS fingerprinting, and scan-vulnerabilities to run NSE scripts in safe categories. Use these tools in sequence to perform a structured security assessment: start by discovering live hosts, followed by a quick overview, then deeper port scanning, service detection, OS fingerprinting (where root access is available), and finally vulnerability checks with NSE. The server is Docker-based, making it easy to integrate with any MCP client like Claude, Cursor, Windsurf, or VS Code Copilot. Each tool supports input validation and sensible defaults to keep usage safe in autonomous workflows.

Prerequisites:

• Docker installed and running
• Optional: Python 3.10+ if you prefer building from source, and Nmap installed on PATH if you plan to run locally outside Docker

Installation steps (Docker, recommended):

1. Build the Docker image

docker build -t nmap-mcp https://github.com/vorotaai/nmap-mcp.git

2. Run the container (example):

docker run --rm -i nmap-mcp

3. Configure MCP client to connect to this server (example configuration):

{
  "mcpServers": {
    "nmap-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "nmap-mcp"]
    }
  }
}

If you prefer building from source (requires Python 3.10+, Nmap on PATH, and uv):

1. Clone the repository

git clone https://github.com/vorotaai/nmap-mcp.git
cd nmap-mcp

2. Install/run with uv (advanced users)

uv sync --all-groups
nmap-mcp

3. Ensure Nmap is accessible via PATH and environment variables are configured as needed.

Environment variables allow tuning and safety controls:

• NMAP_BINARY: path to the Nmap binary (default: nmap)
• NMAP_SCAN_TIMEOUT: maximum duration per scan (default: 600 seconds)
• NMAP_MAX_TARGETS: max number of targets per scan (default: 256)
• FASTMCP_LOG_LEVEL: logging level (DEBUG, INFO, WARNING, ERROR; default: WARNING)

Common issues:

• Ensure you have explicit authorization to scan the target network.
• If OS fingerprinting (detect-os) requires root, run with appropriate privileges.
• For large networks, adjust NMAP_MAX_TARGETS and NMAP_SCAN_TIMEOUT to avoid timeouts or excessive load.
• When using Docker, ensure the image name matches and the container has network access to targets.

Configuration tips:

• Use the provided example mcpServers config blocks to wire the server into MCP clients.
• You can override environment variables via the docker run -e options when embedding in client configs.