BlenderMCP

Instructions

Implementation Reference

• src/blender_mcp/server.py:370-419 (handler)

  MCP tool handler for downloading and importing Polyhaven assets into Blender. It proxies parameters to the Blender addon via send_command and formats the response based on asset type.
  @mcp.tool() def download_polyhaven_asset( ctx: Context, asset_id: str, asset_type: str, resolution: str = "1k", file_format: str = None ) -> str: """ Download and import a Polyhaven asset into Blender. Parameters: - asset_id: The ID of the asset to download - asset_type: The type of asset (hdris, textures, models) - resolution: The resolution to download (e.g., 1k, 2k, 4k) - file_format: Optional file format (e.g., hdr, exr for HDRIs; jpg, png for textures; gltf, fbx for models) Returns a message indicating success or failure. """ try: blender = get_blender_connection() result = blender.send_command("download_polyhaven_asset", { "asset_id": asset_id, "asset_type": asset_type, "resolution": resolution, "file_format": file_format }) if "error" in result: return f"Error: {result['error']}" if result.get("success"): message = result.get("message", "Asset downloaded and imported successfully") # Add additional information based on asset type if asset_type == "hdris": return f"{message}. The HDRI has been set as the world environment." elif asset_type == "textures": material_name = result.get("material", "") maps = ", ".join(result.get("maps", [])) return f"{message}. Created material '{material_name}' with maps: {maps}." elif asset_type == "models": return f"{message}. The model has been imported into the current scene." else: return message else: return f"Failed to download asset: {result.get('message', 'Unknown error')}" except Exception as e: logger.error(f"Error downloading Polyhaven asset: {str(e)}") return f"Error downloading Polyhaven asset: {str(e)}"
• src/blender_mcp/server.py:378-388 (schema)

  Docstring defining the input parameters and return type for the download_polyhaven_asset tool, serving as the schema.
  """ Download and import a Polyhaven asset into Blender. Parameters: - asset_id: The ID of the asset to download - asset_type: The type of asset (hdris, textures, models) - resolution: The resolution to download (e.g., 1k, 2k, 4k) - file_format: Optional file format (e.g., hdr, exr for HDRIs; jpg, png for textures; gltf, fbx for models) Returns a message indicating success or failure. """
• src/blender_mcp/server.py:695-746 (helper)

  Prompt template that guides the AI on when and how to use the download_polyhaven_asset tool as part of asset creation strategy.
  @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 """