Nmap MCP Server

Instructions

Implementation Reference

• src/nmap_mcp/server.py:236-349 (handler)

  Executes the run-nmap-scan tool: validates input, checks rate limits and duplicates, runs nmap via subprocess, parses XML output using NmapParser, stores results in global scan_results dict with unique ID, notifies of resource change, returns completion message with scan ID.
  if name == "run-nmap-scan": target = arguments.get("target") options = arguments.get("options", "-sV") # Default to version detection if not target: raise ValueError("Missing target") # Create a unique scan identifier based on target and options scan_key = f"{target}:{options}" # Check if an identical scan is already running if scan_key in ongoing_scans: return [ types.TextContent( type="text", text=f"A scan with the same target and options is already running. Please wait for it to complete.", ) ] # Check rate limiting if not check_rate_limit(): return [ types.TextContent( type="text", text=f"Rate limit exceeded. Please wait before starting another scan. Maximum {RATE_LIMIT_MAX_SCANS} scans per {RATE_LIMIT_PERIOD} seconds.", ) ] try: # Mark this scan as ongoing ongoing_scans.add(scan_key) add_scan_timestamp() logger.info(f"Starting nmap scan on {target} with options {options}") # Use direct subprocess call instead of NmapProcess stdout, stderr = run_nmap_directly(target, options) if stderr: logger.error(f"Nmap scan failed: {stderr}") return [ types.TextContent( type="text", text=f"Nmap scan failed: {stderr}", ) ] # Parse results - convert bytes to string first try: xml_string = stdout.decode('utf-8', errors='replace') parsed = NmapParser.parse_fromstring(xml_string) except Exception as e: logger.error(f"Error parsing nmap results: {str(e)}") return [ types.TextContent( type="text", text=f"Error parsing nmap results: {str(e)}", ) ] # Generate a unique ID for this scan scan_id = str(uuid.uuid4()) # Store scan results scan_results[scan_id] = { "target": target, "options": options, "timestamp": parsed.started, "hosts": [ { "address": host.address, "status": host.status, "hostnames": [ hostname.name if hasattr(hostname, 'name') else str(hostname) for hostname in host.hostnames ], "services": [ { "port": service.port, "protocol": service.protocol, "state": service.state, "service": service.service, "banner": service.banner } for service in host.services ] } for host in parsed.hosts ] } # Notify clients that new resources are available await server.request_context.session.send_resource_list_changed() logger.info(f"Scan completed. Found {len(parsed.hosts)} hosts. Scan ID: {scan_id}") return [ types.TextContent( type="text", text=f"Scan completed. Found {len(parsed.hosts)} hosts. Scan ID: {scan_id}", ) ] except Exception as e: logger.error(f"Error during nmap scan: {str(e)}") return [ types.TextContent( type="text", text=f"Error during nmap scan: {str(e)}", ) ] finally: # Remove from ongoing scans when done ongoing_scans.discard(scan_key)
• src/nmap_mcp/server.py:148-159 (registration)

  Registers the 'run-nmap-scan' tool in the list_tools() handler, including name, description, and input schema definition.
  types.Tool( name="run-nmap-scan", description="Run an nmap scan on specified targets", inputSchema={ "type": "object", "properties": { "target": {"type": "string", "description": "Target host or network (e.g., 192.168.1.1 or 192.168.1.0/24)"}, "options": {"type": "string", "description": "Nmap options (e.g., -sV -p 1-1000)"}, }, "required": ["target"], }, ),
• src/nmap_mcp/server.py:197-225 (helper)

  Helper function to execute nmap command via subprocess.Popen equivalent (subprocess.run), capturing XML output for parsing.
  def run_nmap_directly(target, options): """Run nmap directly using subprocess instead of relying on python-libnmap.""" try: # Construct the basic command with XML output cmd = [NMAP_PATH, "-oX", "-"] # Split options into separate arguments if options: option_args = options.split() cmd.extend(option_args) # Add target at the end cmd.append(target) logger.info(f"Executing nmap command: {' '.join(cmd)}") # Run the command and capture both stdout and stderr process = subprocess.run( cmd, capture_output=True, text=False, check=True ) return process.stdout, None except subprocess.CalledProcessError as e: return None, f"nmap failed with exit code {e.returncode}: {e.stderr.decode('utf-8', errors='replace')}" except Exception as e: return None, str(e)
• src/nmap_mcp/server.py:151-158 (schema)

  Input schema for the run-nmap-scan tool, defining target (required) and options parameters.
  inputSchema={ "type": "object", "properties": { "target": {"type": "string", "description": "Target host or network (e.g., 192.168.1.1 or 192.168.1.0/24)"}, "options": {"type": "string", "description": "Nmap options (e.g., -sV -p 1-1000)"}, }, "required": ["target"], },