BlenderMCP

Instructions

Implementation Reference

• src/blender_mcp/server.py:742-796 (handler)

  The core handler function for the 'generate_hyper3d_model_via_images' MCP tool. It validates input images (either paths or URLs), encodes path-based images to base64, processes bbox_condition using helper, and sends a 'create_rodin_job' command to Blender addon via socket. The @mcp.tool() decorator registers the tool and infers schema from signature/docstring.

  @mcp.tool()
  def generate_hyper3d_model_via_images(
      ctx: Context,
      input_image_paths: list[str]=None,
      input_image_urls: list[str]=None,
      bbox_condition: list[float]=None
  ) -> str:
      """
      Generate 3D asset using Hyper3D by giving images of the wanted asset, and import the generated asset into Blender.
      The 3D asset has built-in materials.
      The generated model has a normalized size, so re-scaling after generation can be useful.
      
      Parameters:
      - input_image_paths: The **absolute** paths of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in MAIN_SITE mode.
      - input_image_urls: The URLs of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in FAL_AI mode.
      - bbox_condition: Optional. If given, it has to be a list of ints of length 3. Controls the ratio between [Length, Width, Height] of the model.
  
      Only one of {input_image_paths, input_image_urls} should be given at a time, depending on the Hyper3D Rodin's current mode.
      Returns a message indicating success or failure.
      """
      if input_image_paths is not None and input_image_urls is not None:
          return f"Error: Conflict parameters given!"
      if input_image_paths is None and input_image_urls is None:
          return f"Error: No image given!"
      if input_image_paths is not None:
          if not all(os.path.exists(i) for i in input_image_paths):
              return "Error: not all image paths are valid!"
          images = []
          for path in input_image_paths:
              with open(path, "rb") as f:
                  images.append(
                      (Path(path).suffix, base64.b64encode(f.read()).decode("ascii"))
                  )
      elif input_image_urls is not None:
          if not all(urlparse(i) for i in input_image_paths):
              return "Error: not all image URLs are valid!"
          images = input_image_urls.copy()
      try:
          blender = get_blender_connection()
          result = blender.send_command("create_rodin_job", {
              "text_prompt": None,
              "images": images,
              "bbox_condition": _process_bbox(bbox_condition),
          })
          succeed = result.get("submit_time", False)
          if succeed:
              return json.dumps({
                  "task_uuid": result["uuid"],
                  "subscription_key": result["jobs"]["subscription_key"],
              })
          else:
              return json.dumps(result)
      except Exception as e:
          logger.error(f"Error generating Hyper3D task: {str(e)}")
          return f"Error generating Hyper3D task: {str(e)}"

• src/blender_mcp/server.py:697-704 (helper)

  Helper function used by the tool to normalize bbox_condition into percentages (0-100) based on max dimension, handling float/int inputs.

  def _process_bbox(original_bbox: list[float] | list[int] | None) -> list[int] | None:
      if original_bbox is None:
          return None
      if all(isinstance(i, int) for i in original_bbox):
          return original_bbox
      if any(i<=0 for i in original_bbox):
          raise ValueError("Incorrect number range: bbox must be bigger than zero!")
      return [int(float(i) / max(original_bbox) * 100) for i in original_bbox] if original_bbox else None

• src/blender_mcp/server.py:540-557 (helper)

  Utility tool to check Hyper3D status, prerequisite for using the generation tools.

  def get_hyper3d_status(ctx: Context) -> str:
      """
      Check if Hyper3D Rodin integration is enabled in Blender.
      Returns a message indicating whether Hyper3D Rodin features are available.
  
      Don't emphasize the key type in the returned message, but sliently remember it. 
      """
      try:
          blender = get_blender_connection()
          result = blender.send_command("get_hyper3d_status")
          enabled = result.get("enabled", False)
          message = result.get("message", "")
          if enabled:
              message += ""
          return message
      except Exception as e:
          logger.error(f"Error checking Hyper3D status: {str(e)}")
          return f"Error checking Hyper3D status: {str(e)}"