Nmap MCP Server

How to use

You interact with the Nmap MCP Server from an MCP client. Start by configuring the MCP client to connect to the HTTP endpoint, using either a URL token or a Bearer Token, then issue scan commands such as quick_scan, full_scan, or custom_scan. You can submit a scan request and either wait for a synchronous result within the configured timeout or retrieve the result later if the scan runs asynchronously. Access a scan’s status and final structured JSON results to review opened ports, their states, and services.

How to install

Prerequisites: Python 3.10+ and Nmap installed on the system.

Clone the project, set up a Python virtual environment, install dependencies, initialize the configuration template, and prepare a real config file.

# Clone the project
git clone <repository-url>
cd nmap-mcp-http

# Create a virtual environment
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# or venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Generate configuration template
python server.py --init

# Copy the example config and edit it
cp config.example.json config.json
vim config.json  # modify token and settings

Configuration details

Key configuration values in config.json include the host, port, path, and authentication token, plus timing and resource limits. You set where the server listens, how long synchronous scans wait before an asynchronous fallback, and how many tasks can run concurrently.

{
  "host": "0.0.0.0",
  "port": 3004,
  "path": "/mcp",
  "token": "your_secret_token_here",
  "sync_timeout": 30,
  "max_concurrent_tasks": 10,
  "db_path": "nmap_tasks.db",
  "nmap_path": "nmap"
}

Run and manage the service

Start the server with your chosen configuration file. You can use the default config.json or specify a custom path to the configuration.

# With the default config.json
python server.py

# With a specific config file
python server.py -c /path/to/config.json

# Generate a new configuration template again if needed
python server.py --init

Client authentication configurations

Two authentication methods are supported for MCP clients.

# Method 1: URL Token
{
  "mcpServers": {
    "nmap-scanner": {
      "name": "Nmap Scanner",
      "type": "streamableHttp",
      "description": "Nmap 端口扫描服务",
      "isActive": true,
      "baseUrl": "http://127.0.0.1:3004/mcp?token=your_token"
    }
  }
}

Client authentication configurations (Bearer Token)

{
  "mcpServers": {
    "nmap-scanner": {
      "name": "Nmap Scanner",
      "type": "streamableHttp",
      "description": "Nmap 端口扫描服务",
      "isActive": true,
      "baseUrl": "http://127.0.0.1:3004/mcp",
      "headers": {
        "Authorization": "Bearer your_token"
      }
    }
  }
}

Troubleshooting and tips

Be mindful of resource usage when scanning large ranges. Asynchronous task mode helps avoid long blocking times. Change the token from the default to prevent unauthorized access and consider deploying within a secure network or behind a firewall.

quick_scan

Performs a fast scan of commonly used ports on the target, returning a concise result with port states and services.

full_scan

Performs a comprehensive scan of all 1-65535 ports, including version detection.

custom_scan

Executes a user-specified Nmap command with provided arguments.

get_task_status

Queries the status of an existing scan task by its UUID.

get_task_result

Retrieves the complete structured result for a finished task.