Nmap MCP Server

Instructions

Implementation Reference

• server.py:221-224 (registration)

  Registers the 'nmap_ping_scan' tool using the FastMCP @app.tool decorator, specifying its name and description.

  @app.tool(
      name="nmap_ping_scan",
      description="Perform ping scan to discover live hosts"
  )

• server.py:225-242 (handler)

  The main handler function for the 'nmap_ping_scan' tool. It constructs Nmap arguments based on the ping_type parameter (icmp, tcp, or both), executes the scan using the shared run_nmap_command helper, and returns the formatted results or error message.

  async def nmap_ping_scan(
      targets: str,
      ping_type: str = "both"
  ) -> str:
      """Perform ping scan to discover live hosts."""
      if ping_type == "icmp":
          args = ["-sn", targets]
      elif ping_type == "tcp":
          args = ["-PS", targets]
      else:  # both
          args = ["-sn", "-PS", targets]
      
      result = run_nmap_command(args)
      
      if result["success"]:
          return f"Ping scan completed:\n\n{result['stdout']}"
      else:
          return f"Ping scan failed:\n\n{result['stderr']}"

• server.py:38-92 (helper)

  Shared utility function used by nmap_ping_scan (and other tools) to execute Nmap commands via subprocess, handling output, errors, timeouts, and providing structured results.

  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
          }