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