BlenderMCP

Instructions

Implementation Reference

• src/blender_mcp/server.py:563-619 (handler)

  The handler function for the 'generate_hyper3d_model_via_images' tool. Processes input image paths or URLs, validates and encodes images from paths to base64, sends a 'create_rodin_job' command to the Blender connection with images and optional bbox_condition (processed by _process_bbox), and returns JSON with task_uuid and subscription_key on success or error details.
  @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)}" @mcp.tool()
• src/blender_mcp/server.py:518-525 (helper)

  Helper function used by the generate_hyper3d_model_via_images tool 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:564-582 (schema)

  The function signature and docstring define the input schema (parameters: input_image_paths, input_image_urls, bbox_condition) and output (str with JSON task info or error). Note: docstring mentions bbox as list of ints but signature is list[float].
  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. """
• src/blender_mcp/server.py:563-563 (registration)

  The @mcp.tool() decorator registers this function as an MCP tool named 'generate_hyper3d_model_via_images'.
  @mcp.tool()
• src/blender_mcp/server.py:695-745 (helper)

  The asset_creation_strategy prompt includes instructions on using generate_hyper3d_model_via_images as part of the preferred asset creation workflow when Hyper3D is enabled.
  @mcp.prompt() def asset_creation_strategy() -> str: """Defines the preferred strategy for creating assets in Blender""" return """When creating 3D content in Blender, always start by checking if integrations are available: 0. Before anything, always check the scene from get_scene_info() 1. First use the following tools to verify if the following integrations are enabled: 1. PolyHaven Use get_polyhaven_status() to verify its status If PolyHaven is enabled: - For objects/models: Use download_polyhaven_asset() with asset_type="models" - For materials/textures: Use download_polyhaven_asset() with asset_type="textures" - For environment lighting: Use download_polyhaven_asset() with asset_type="hdris" 2. Hyper3D(Rodin) Hyper3D Rodin is good at generating 3D models for single item. So don't try to: 1. Generate the whole scene with one shot 2. Generate ground using Hyper3D 3. Generate parts of the items separately and put them together afterwards Use get_hyper3d_status() to verify its status If Hyper3D is enabled: - For objects/models, do the following steps: 1. Create the model generation task - Use generate_hyper3d_model_via_images() if image(s) is/are given - Use generate_hyper3d_model_via_text() if generating 3D asset using text prompt If key type is free_trial and insufficient balance error returned, tell the user that the free trial key can only generated limited models everyday, they can choose to: - Wait for another day and try again - Go to hyper3d.ai to find out how to get their own API key - Go to fal.ai to get their own private API key 2. Poll the status - Use poll_rodin_job_status() to check if the generation task has completed or failed 3. Import the asset - Use import_generated_asset() to import the generated GLB model the asset 4. After importing the asset, ALWAYS check the world_bounding_box of the imported mesh, and adjust the mesh's location and size Adjust the imported mesh's location, scale, rotation, so that the mesh is on the right spot. You can reuse assets previous generated by running python code to duplicate the object, without creating another generation task. 3. Always check the world_bounding_box for each item so that: - Ensure that all objects that should not be clipping are not clipping. - Items have right spatial relationship. Only fall back to scripting when: - PolyHaven and Hyper3D are disabled - A simple primitive is explicitly requested - No suitable PolyHaven asset exists - Hyper3D Rodin failed to generate the desired asset - The task specifically requires a basic material/color """