download_polyhaven_asset

Instructions

Implementation Reference

• src/blender_mcp/server.py:416-465 (handler)

  The MCP tool handler function for 'download_polyhaven_asset'. Decorated with @mcp.tool(), it handles input parameters, sends a 'download_polyhaven_asset' command to the Blender connection, processes the result, and returns formatted success/error messages with type-specific details.

  @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:424-434 (schema)

  The docstring within the handler defines the input schema (parameters and descriptions) and output description for the tool.

  """
  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:416-416 (registration)

  The @mcp.tool() decorator registers this function as an MCP tool.

  @mcp.tool()

• src/blender_mcp/server.py:879-943 (helper)

  MCP prompt that provides strategy guidance, including specific usage instructions for the download_polyhaven_asset tool based on asset_type.

  @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. Sketchfab
              Sketchfab is good at Realistic models, and has a wider variety of models than PolyHaven.
              Use get_sketchfab_status() to verify its status
              If Sketchfab is enabled:
              - For objects/models: First search using search_sketchfab_models() with your query
              - Then download specific models using download_sketchfab_model() with the UID
              - Note that only downloadable models can be accessed, and API key must be properly configured
              - Sketchfab has a wider variety of models than PolyHaven, especially for specific subjects
          3. 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.
      
      4. Recommended asset source priority:
          - For specific existing objects: First try Sketchfab, then PolyHaven
          - For generic objects/furniture: First try PolyHaven, then Sketchfab
          - For custom or unique items not available in libraries: Use Hyper3D Rodin
          - For environment lighting: Use PolyHaven HDRIs
          - For materials/textures: Use PolyHaven textures
  
      Only fall back to scripting when:
      - PolyHaven, Sketchfab, and Hyper3D are all disabled
      - A simple primitive is explicitly requested
      - No suitable asset exists in any of the libraries
      - Hyper3D Rodin failed to generate the desired asset
      - The task specifically requires a basic material/color
      """