Vert.x MCP Nmap Server

Simple MCP server implemented with Java and Vert.x. Exposes two tools:

• nmap_scan_ports: Scan a host with nmap (optional ports).
• nmap_scan_lan: Scan local network for devices with nmap.

A fun little tool to learn MCP in depth.

Requirements

• Java 17+
• nmap installed and available on PATH

Build and run

mvn package
java -jar target/nmap-mcp-wrapper-0.1.0-fat.jar

Server listens on http://localhost:8080/mcp by default. Set PORT to change.

MCP client config

Example MCP client config, differs depending on the client at hand. Example is for Cursor.

{
    "mcpServers": {
      "nmap-wrapper-server": {
        "url": "http://localhost:8080/mcp"
      }
    }
}

MCP requests

Initialize:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

List tools:

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

Call tools:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"nmap_scan_ports","arguments":{"host":"scanme.nmap.org","ports":"22,80,443"}}}

{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"nmap_scan_lan","arguments":{"cidr":"192.168.1.0/24"}}}

If cidr is omitted, the server attempts to detect the first non-loopback IPv4 interface and scans a /24 network.