Nmap MCP Server

Instructions

Implementation Reference

• server.py:97-119 (handler)

  The main handler function for the nmap_basic_scan tool. It constructs Nmap command arguments based on the scan_type parameter (quick, comprehensive, or stealth) and executes the scan using the run_nmap_command helper.

  async def nmap_basic_scan(
      targets: str,
      ports: str = "common",
      scan_type: str = "quick"
  ) -> str:
      """Perform a basic Nmap scan of specified targets."""
      args = ["-p", ports]
      
      if scan_type == "quick":
          args.extend(["-T4", "--min-rate=1000"])
      elif scan_type == "comprehensive":
          args.extend(["-sS", "-sV", "-O", "--script=default"])
      elif scan_type == "stealth":
          args.extend(["-sS", "-T2", "--min-rate=100"])
      
      args.append(targets)
      
      result = run_nmap_command(args)
      
      if result["success"]:
          return f"Basic scan completed successfully:\n\n{result['stdout']}"
      else:
          return f"Basic scan failed:\n\n{result['stderr']}"

• server.py:93-96 (registration)

  Registers the nmap_basic_scan tool with the FastMCP app using the @app.tool decorator, specifying the name and description.

  @app.tool(
      name="nmap_basic_scan",
      description="Perform a basic Nmap scan of specified targets"
  )

• server.py:38-91 (helper)

  Shared helper function used by nmap_basic_scan (and other tools) to execute Nmap commands via subprocess, handling timeouts, errors, and parsing output.

  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
          }