BlenderMCP

Instructions

Implementation Reference

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

  The MCP tool handler for 'download_polyhaven_asset'. It validates inputs via type hints and docstring, sends the download command to the Blender addon socket server, handles the response, and provides type-specific success messages. The function signature defines the input schema.

  @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:370-370 (registration)

  The @mcp.tool() decorator registers the 'download_polyhaven_asset' function as an MCP tool.

  @mcp.tool()

• src/blender_mcp/server.py:378-388 (schema)

  Docstring defining the input parameters and usage for the tool 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:705-707 (helper)

  Documentation in the asset_creation_strategy prompt recommending usage of the tool for different asset types.

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