Nmap MCP Server

Instructions

Implementation Reference

• server.py:268-271 (registration)

  Registration of the nmap_vulnerability_scan tool using FastMCP @app.tool decorator.

  @app.tool(
      name="nmap_vulnerability_scan",
      description="Run vulnerability detection scripts"
  )

• server.py:272-290 (handler)

  The main handler function that constructs Nmap arguments for vulnerability scripts based on parameters and executes via run_nmap_command.

  async def nmap_vulnerability_scan(
      targets: str,
      ports: str = "common",
      vuln_category: str = "all"
  ) -> str:
      """Run vulnerability detection scripts."""
      if vuln_category == "all":
          scripts = "vuln"
      else:
          scripts = f"vuln and {vuln_category}"
      
      args = [f"--script={scripts}", "-p", ports, targets]
      
      result = run_nmap_command(args, timeout=600)
      
      if result["success"]:
          return f"Vulnerability scan completed:\n\n{result['stdout']}"
      else:
          return f"Vulnerability scan failed:\n\n{result['stderr']}"

• server.py:38-91 (helper)

  Helper function that executes nmap commands using subprocess, handles timeouts and errors, and returns structured results. Used by all nmap tools including this one.

  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
          }