BlenderMCP

Instructions

Implementation Reference

• src/blender_mcp/server.py:770-825 (handler)

  The handler function that executes the tool logic: processes input image paths or URLs, validates them, encodes images if from paths, normalizes bbox_condition, sends 'create_rodin_job' command to Blender addon, and returns task UUID and subscription key or error.

  @telemetry_tool("generate_hyper3d_model_via_images")
  @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:724-731 (helper)

  Supporting utility function used in the handler to normalize the bbox_condition input into a list of integers scaled to 0-100 range based on the maximum value.

  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:770-771 (registration)

  Decorators that register the tool with the MCP server (@mcp.tool()) and add telemetry tracking (@telemetry_tool).

  @telemetry_tool("generate_hyper3d_model_via_images")
  @mcp.tool()

• src/blender_mcp/server.py:778-790 (schema)

  Input schema and documentation defined in the function docstring, describing parameters, usage constraints, and return format for the MCP tool.

  """
  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.
  """