nmap-mcp

nmap-mcp

   

A Model Context Protocol (MCP) server that provides comprehensive network scanning capabilities using nmap. Designed for security professionals and penetration testers, this server can execute scans either locally or via SSH on a remote Kali Linux box for security isolation.

Features

• Multiple Scan Types: Port scanning, service detection, OS fingerprinting, vulnerability assessment
• NSE Script Support: Run 600+ Nmap Scripting Engine scripts
• Flexible Execution: Run locally or via SSH to a remote scanning host
• Structured Output: Parsed XML results formatted as readable Markdown
• Security-First: Input validation to prevent command injection
• Stealth Options: Decoys, fragmentation, timing controls for evasive scanning

Installation

# Clone the repository
git clone https://github.com/schwarztim/sec-nmap-mcp.git
cd sec-nmap-mcp

# Install dependencies
npm install

# Build
npm run build

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | NMAP_SSH_HOST | SSH host for remote execution | kali | | NMAP_SSH_USER | SSH username (optional) | Uses SSH config default | | NMAP_SSH_KEY | Path to SSH private key (optional) | Uses SSH config default | | NMAP_LOCAL | Set to "true" to run nmap locally | false |

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "nmap": {
      "command": "node",
      "args": ["/path/to/sec-nmap-mcp/dist/index.js"],
      "env": {
        "NMAP_SSH_HOST": "kali",
        "NMAP_LOCAL": "false"
      }
    }
  }
}

For local execution:

{
  "mcpServers": {
    "nmap": {
      "command": "node",
      "args": ["/path/to/sec-nmap-mcp/dist/index.js"],
      "env": {
        "NMAP_LOCAL": "true"
      }
    }
  }
}

Available Tools

Basic Scanning

| Tool | Description | |------|-------------| | nmap_scan | Basic port scan with customizable options | | nmap_quick_scan | Fast scan of common ports (-F) | | nmap_ping_sweep | Host discovery without port scanning (-sn) |

Advanced Scanning

| Tool | Description | |------|-------------| | nmap_service_scan | Service version detection (-sV) | | nmap_os_detect | OS fingerprinting (-O) | | nmap_comprehensive_scan | Full scan: SYN + version + OS + scripts | | nmap_stealth_scan | Evasive scan with decoys and fragmentation |

Security Assessment

| Tool | Description | |------|-------------| | nmap_script_scan | Run specific NSE scripts | | nmap_vuln_scan | Vulnerability assessment scripts |

Utility

| Tool | Description | |------|-------------| | nmap_status | Check nmap availability and configuration | | nmap_parse_output | Parse existing nmap XML output |

Usage Examples

Basic Port Scan

Scan target 192.168.1.1 for open ports

Service Version Detection

Run a service scan on 10.0.0.0/24 ports 22,80,443

Vulnerability Assessment

Run a vulnerability scan on target.example.com

Stealth Scan with Decoys

Perform a stealth scan on 192.168.1.100 using random decoys

Ping Sweep for Host Discovery

Find all live hosts on 192.168.1.0/24

NSE Script Scan

Run the http-title and ssl-cert scripts on example.com port 443

Security Considerations

Remote Execution (Recommended)

Running nmap via SSH to a dedicated Kali Linux box provides:

• Isolation: Scans originate from a controlled environment
• Privilege Management: Root access for advanced scans without local elevation
• Audit Trail: Centralized logging on the scanning host
• Network Segmentation: Scan traffic separated from workstation

Input Validation

The server validates all inputs to prevent command injection:

• Targets are validated against allowed character patterns
• Dangerous shell characters are blocked
• Port specifications are strictly validated

Responsible Use

This tool is intended for:

• Security assessments with proper authorization
• Network inventory and management
• Educational purposes

Always ensure you have proper authorization before scanning any network or system.

Development

# Watch mode for development
npm run dev

# Build for production
npm run build

# Run the server
npm start

Requirements

• Node.js 18+
• nmap installed (locally or on SSH target)
• SSH access to remote host (if using remote execution)

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• Nmap - The Network Mapper
• Model Context Protocol - AI tool integration standard