Frida MCP

Instructions

Returns:
    A list of process information dictionaries containing:
    - pid: Process ID
    - name: Process name

Implementation Reference

• src/frida_mcp/cli.py:206-222 (handler)

  The handler function for the MCP tool 'enumerate_processes'. Decorated with @mcp.tool(), it resolves a Frida device using _resolve_device_or_raise, enumerates processes via Frida's device.enumerate_processes(), and returns a list of dictionaries with pid and name.

  @mcp.tool()
  def enumerate_processes(
      device_id: Optional[str] = Field(
          default=None,
          description="Optional ID of the device to enumerate processes from. Uses smart selection when omitted.",
      ),
  ) -> List[Dict[str, Any]]:
      """List all processes running on the system.
  
      Returns:
          A list of process information dictionaries containing:
          - pid: Process ID
          - name: Process name
      """
      device = _resolve_device_or_raise(device_id)
      processes = device.enumerate_processes()
      return [{"pid": process.pid, "name": process.name} for process in processes]

• src/frida_mcp/cli.py:444-449 (helper)

  A related MCP resource that also uses device.enumerate_processes() to list processes as a string.

  @mcp.resource("frida://processes")
  def get_processes_resource() -> str:
      """Get a list of processes from the currently selected default device as a readable string."""
      device = _resolve_device_or_raise()
      processes = device.enumerate_processes()
      return "\n".join([f"PID: {p.pid}, Name: {p.name}" for p in processes])

• src/frida_mcp/cli.py:197-436 (helper)

  Helper function used by the tool to resolve the Frida device, imported from device_selection.py but wrapped to raise ValueError.

              raise ValueError(f"{exc}. Attempts: {attempts}") from exc
          logger.error(
              "Device resolution failed for id=%s: %s",
              device_id or "<default>",
              exc,
          )
          raise ValueError(str(exc)) from exc
  
  
  @mcp.tool()
  def enumerate_processes(
      device_id: Optional[str] = Field(
          default=None,
          description="Optional ID of the device to enumerate processes from. Uses smart selection when omitted.",
      ),
  ) -> List[Dict[str, Any]]:
      """List all processes running on the system.
  
      Returns:
          A list of process information dictionaries containing:
          - pid: Process ID
          - name: Process name
      """
      device = _resolve_device_or_raise(device_id)
      processes = device.enumerate_processes()
      return [{"pid": process.pid, "name": process.name} for process in processes]
  
  
  @mcp.tool()
  def enumerate_devices() -> List[Dict[str, Any]]:
      """List all devices connected to the system.
  
      Returns:
          A list of device information dictionaries containing:
          - id: Device ID
          - name: Device name
          - type: Device type
          - hint: How to reference the device via device_id
          - alias: Configured alias for remote devices (if any)
          - default_candidate: Whether the device is the current default choice
      """
      return describe_devices()
  
  
  @mcp.tool()
  def configure_remote_device(
      address: str = Field(description="The remote <host>:<port> to add."),
      alias: Optional[str] = Field(
          default=None,
          description="Optional alias used as device_id when targeting this remote.",
      ),
      set_as_default: bool = Field(
          default=False,
          description="If true, future requests without device_id will prefer this remote.",
      ),
  ) -> Dict[str, Any]:
      """Connect to a remote Frida server and make it available for future requests."""
  
      try:
          info = register_remote_device(address, alias=alias, set_default=set_as_default)
      except DeviceSelectionError as exc:
          if exc.reasons:
              attempts = "; ".join(exc.reasons)
              raise ValueError(f"{exc}. Attempts: {attempts}") from exc
          raise ValueError(str(exc)) from exc
  
      response: Dict[str, Any] = {"status": "success"}
      response.update(info)
      if set_as_default:
          response["message"] = "Remote device set as default"
      return response
  
  
  @mcp.tool()
  def get_device(
      device_id: str = Field(description="The ID of the device to get"),
  ) -> Dict[str, Any]:
      """Get a device by its ID.
  
      Returns:
          Information about the device
      """
      device = _resolve_device_or_raise(device_id)
      return {
          "id": device.id,
          "name": device.name,
          "type": device.type,
      }
  
  
  @mcp.tool()
  def get_usb_device() -> Dict[str, Any]:
      """Get the USB device connected to the system.
  
      Returns:
          Information about the USB device
      """
      try:
          device = frida.get_usb_device()
          return {
              "id": device.id,
              "name": device.name,
              "type": device.type,
          }
      except frida.InvalidArgumentError:
          raise ValueError("No USB device found")
  
  
  @mcp.tool()
  def get_local_device() -> Dict[str, Any]:
      """Get the local device.
  
      Returns:
          Information about the local device
      """
      try:
          device = frida.get_local_device()
          return {
              "id": device.id,
              "name": device.name,
              "type": device.type,
          }
      except frida.InvalidArgumentError:  # Or other relevant Frida exceptions
          raise ValueError("No local device found or error accessing it.")
  
  
  @mcp.tool()
  def get_process_by_name(
      name: str = Field(
          description="The name (or part of the name) of the process to find. Case-insensitive."
      ),
      device_id: Optional[str] = Field(
          default=None,
          description="Optional ID of the device to search the process on. Uses smart selection when omitted.",
      ),
  ) -> dict:
      """Find a process by name."""
      device = _resolve_device_or_raise(device_id)
      for proc in device.enumerate_processes():
          if name.lower() in proc.name.lower():
              return {"pid": proc.pid, "name": proc.name, "found": True}
      return {"found": False, "error": f"Process '{name}' not found"}
  
  
  @mcp.tool()
  def attach_to_process(
      pid: int = Field(description="The ID of the process to attach to."),
      device_id: Optional[str] = Field(
          default=None,
          description="Optional ID of the device where the process is running. Uses smart selection when omitted.",
      ),
  ) -> dict:
      """Attach to a process by ID."""
      try:
          device = _resolve_device_or_raise(device_id)
          device.attach(pid)
          return {
              "pid": pid,
              "success": True,
              "is_detached": False,  # New session is not detached
          }
      except Exception as e:
          return {"success": False, "error": str(e)}
  
  
  @mcp.tool()
  def spawn_process(
      program: str = Field(description="The program or application identifier to spawn."),
      args: Optional[List[str]] = Field(
          default=None, description="Optional list of arguments for the program."
      ),
      device_id: Optional[str] = Field(
          default=None,
          description="Optional ID of the device where the program should be spawned. Uses smart selection when omitted.",
      ),
  ) -> Dict[str, Any]:
      """Spawn a program.
  
      Returns:
          Information about the spawned process
      """
      try:
          device = _resolve_device_or_raise(device_id)
  
          argv = None
          if args:
              argv = list(args)
              if not argv or argv[0] != program:
                  argv.insert(0, program)
  
          pid = device.spawn(program, argv=argv)
  
          return {"pid": pid}
      except Exception as e:
          raise ValueError(f"Failed to spawn {program}: {str(e)}")
  
  
  @mcp.tool()
  def resume_process(
      pid: int = Field(description="The ID of the process to resume."),
      device_id: Optional[str] = Field(
          default=None,
          description="Optional ID of the device where the process is running. Uses smart selection when omitted.",
      ),
  ) -> Dict[str, Any]:
      """Resume a process by ID.
  
      Returns:
          Status information
      """
      try:
          device = _resolve_device_or_raise(device_id)
          device.resume(pid)
  
          return {"success": True, "pid": pid}
      except Exception as e:
          raise ValueError(f"Failed to resume process {pid}: {str(e)}")
  
  
  @mcp.tool()
  def kill_process(
      pid: int = Field(description="The ID of the process to kill."),
      device_id: Optional[str] = Field(
          default=None,
          description="Optional ID of the device where the process is running. Uses smart selection when omitted.",
      ),
  ) -> Dict[str, Any]:
      """Kill a process by ID.
  
      Returns:
          Status information
      """
      try:
          device = _resolve_device_or_raise(device_id)
          device.kill(pid)
  
          return {"success": True, "pid": pid}
      except Exception as e:
          raise ValueError(f"Failed to kill process {pid}: {str(e)}")