Nmap MCP Server

Instructions

Implementation Reference

• server.py:325-349 (handler)

  The main handler function for the nmap_custom_scan tool. It parses custom options, appends targets, executes via run_nmap_command, and returns formatted output or error.

  async def nmap_custom_scan(
      targets: str,
      custom_options: str,
      output_format: str = "normal"
  ) -> str:
      """Perform custom Nmap scan with user-defined options."""
      # Parse custom options
      args = custom_options.split()
      
      # Add output format if specified
      if output_format == "xml":
          args.append("-oX")
          args.append("-")
      elif output_format == "grepable":
          args.append("-oG")
          args.append("-")
      
      args.append(targets)
      
      result = run_nmap_command(args)
      
      if result["success"]:
          return f"Custom scan completed:\n\n{result['stdout']}"
      else:
          return f"Custom scan failed:\n\n{result['stderr']}"

• server.py:321-324 (registration)

  Registration of the nmap_custom_scan tool using the @app.tool decorator with name and description.

  @app.tool(
      name="nmap_custom_scan",
      description="Perform custom Nmap scan with user-defined options"
  )

• server.py:38-92 (helper)

  Shared helper function used by all nmap tools, including nmap_custom_scan, to execute nmap commands via subprocess and handle results/errors.

  def run_nmap_command(args: List[str], timeout: int = 300) -> Dict[str, Any]:
      """
      Execute an nmap command and return the results.
      
      Args:
          args: List of nmap command arguments
          timeout: Command timeout in seconds
      
      Returns:
          Dictionary containing command output, error, and exit code
      """
      try:
          # Construct the full nmap command
          cmd = ["nmap"] + args
          
          logger.info(f"Executing nmap command: {' '.join(cmd)}")
          
          # Run the command with timeout
          result = subprocess.run(
              cmd,
              capture_output=True,
              text=True,
              timeout=timeout,
              check=False
          )
          
          return {
              "stdout": result.stdout,
              "stderr": result.stderr,
              "exit_code": result.returncode,
              "success": result.returncode == 0
          }
          
      except subprocess.TimeoutExpired:
          return {
              "stdout": "",
              "stderr": f"Command timed out after {timeout} seconds",
              "exit_code": -1,
              "success": False
          }
      except FileNotFoundError:
          return {
              "stdout": "",
              "stderr": "nmap command not found. Please ensure nmap is installed and in PATH",
              "exit_code": -1,
              "success": False
          }
      except Exception as e:
          return {
              "stdout": "",
              "stderr": f"Error executing nmap command: {str(e)}",
              "exit_code": -1,
              "success": False
          }