Nmap

You operate an MCP server that exposes Nmap CLI functionality as reusable tools over a FastMCP stdio transport. This lets you run powerful network scans from your MCP client, automate tasks, and compose complex reconnaissance workflows with consistent tool interfaces.

How to use

You use an MCP client to call the available Nmap tools exposed by the server. Each tool accepts targets and options, performs the corresponding Nmap scan locally, and returns structured results that you can further process in your automation flow. The tools provide practical scan presets (basic, comprehensive, stealth, etc.), service and OS detection, NSE script scanning, and custom option support so you can tailor scans to your needs.

How to install

Prerequisites you need before installation:

• Python 3.10 or higher
• Nmap installed and available in your system PATH

Install Nmap on your operating system using one of the following methods.

# macOS
brew install nmap

# Ubuntu/Debian
sudo apt update
sudo apt install nmap

# CentOS/RHEL
sudo yum install nmap
# or for newer versions:
sudo dnf install nmap

# Windows
# Download and install from nmap.org

Running the FastMCP server

Start the server in stdio transport mode or use the installed script for convenient execution.

# Run directly from the source
python server.py

# Or use the installed CLI entry point
nmap-mcp-server

Claude Desktop configuration

Configure Claude Desktop to connect to your local MCP server using stdio transport. Use the following MCP configuration in Claude Desktop settings.

{
  "mcpServers": {
    "NmapMCP": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/your_user/path/to/nmap-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}

FastMCP tool examples

Use the exposed tools from your MCP client by calling them with appropriate arguments. Examples below illustrate typical usage patterns.

Security considerations

Run scans only on networks and hosts you own or have explicit written permission to assess. Aggressive scans can impact networks and trigger security controls. Use rate limiting and sensible timeouts to avoid unintended disruption.

Error handling and logging

The server includes robust error handling for common issues such as missing Nmap, command timeouts, invalid arguments, network problems, and permission errors. Logging uses Python’s standard logging facility to record command execution details, errors, and performance metrics.

Testing

Validate the MCP setup and tool functionality by running test scripts and example usage to ensure end-to-end operation from the client to the server.

Changelog

Version 1.0.0 introduces the FastMCP implementation, stdio transport, type-safe tool definitions, and a CLI-driven workflow for starting the server and configuring clients.

Available tools

nmap_basic_scan

Perform a basic Nmap scan of specified targets with configurable ports and scan type (quick, comprehensive, stealth).

nmap_service_detection

Detect services and versions on targets with configurable intensity levels.

nmap_os_detection

Detect operating systems on targets with retry controls.

nmap_script_scan

Run Nmap Scripting Engine (NSE) scripts for deeper reconnaissance.

nmap_stealth_scan

Execute SYN stealth scans with configurable timing templates.

nmap_comprehensive_scan

Perform full-featured scans combining multiple detection methods.

nmap_ping_scan

Discover live hosts using ICMP, TCP, or both ping methods.

nmap_port_scan

Scan specific ports with methods like SYN, Connect, or UDP.

nmap_vulnerability_scan

Run vulnerability-focused NSE scripts with category filters.

nmap_network_discovery

Discover hosts and services across entire networks.

nmap_custom_scan

Perform scans with user-defined Nmap options for maximum control.