Nmap MCP Server

Instructions

Implementation Reference

• server.py:296-319 (handler)

  The main asynchronous handler function that implements the logic for the nmap_network_discovery tool. It constructs nmap arguments based on discovery method and port scanning options, executes via run_nmap_command, and returns formatted results.

  async def nmap_network_discovery(
      network: str,
      discovery_method: str = "all",
      include_ports: bool = True
  ) -> str:
      """Discover hosts and services on a network."""
      if discovery_method == "ping":
          args = ["-sn", network]
      elif discovery_method == "arp":
          args = ["-PR", network]
      elif discovery_method == "syn":
          args = ["-PS", network]
      else:  # all
          args = ["-sn", "-PS", "-PA", network]
      
      if include_ports:
          args.extend(["-sS", "-sV", "--top-ports=100"])
      
      result = run_nmap_command(args)
      
      if result["success"]:
          return f"Network discovery completed:\n\n{result['stdout']}"
      else:
          return f"Network discovery failed:\n\n{result['stderr']}"

• server.py:292-295 (registration)

  FastMCP tool registration decorator that registers the nmap_network_discovery handler with the specified name and description.

  @app.tool(
      name="nmap_network_discovery",
      description="Discover hosts and services on a network"
  )

• server.py:38-91 (helper)

  Utility function to execute nmap commands using subprocess, handle timeouts and errors, and return structured results (stdout, stderr, success). Used by multiple tool handlers including nmap_network_discovery.

  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
          }