BlenderMCP

Instructions

Implementation Reference

• src/blender_mcp/server.py:922-958 (handler)

  The core handler function for the generate_hunyuan3d_model tool, decorated with @mcp.tool() for registration. It handles input parameters (text_prompt, input_image_url), sends 'create_hunyuan_job' command to Blender addon via socket, and returns job_id or error.

  @mcp.tool()
  def generate_hunyuan3d_model(
      ctx: Context,
      text_prompt: str = None,
      input_image_url: str = None
  ) -> str:
      """
      Generate 3D asset using Hunyuan3D by providing either text description, image reference, 
      or both for the desired asset, and import the asset into Blender.
      The 3D asset has built-in materials.
      
      Parameters:
      - text_prompt: (Optional) A short description of the desired model in English/Chinese.
      - input_image_url: (Optional) The local or remote url of the input image. Accepts None if only using text prompt.
  
      Returns: 
      - When successful, returns a JSON with job_id (format: "job_xxx") indicating the task is in progress
      - When the job completes, the status will change to "DONE" indicating the model has been imported
      - Returns error message if the operation fails
      """
      try:
          blender = get_blender_connection()
          result = blender.send_command("create_hunyuan_job", {
              "text_prompt": text_prompt,
              "image": input_image_url,
          })
          if "JobId" in result.get("Response", {}):
              job_id = result["Response"]["JobId"]
              formatted_job_id = f"job_{job_id}"
              return json.dumps({
                  "job_id": formatted_job_id,
              })
          return json.dumps(result)
      except Exception as e:
          logger.error(f"Error generating Hunyuan3D task: {str(e)}")
          return f"Error generating Hunyuan3D task: {str(e)}"

• src/blender_mcp/server.py:928-941 (schema)

  The docstring defines the input schema (parameters text_prompt and input_image_url) and output format for the tool.

  """
  Generate 3D asset using Hunyuan3D by providing either text description, image reference, 
  or both for the desired asset, and import the asset into Blender.
  The 3D asset has built-in materials.
  
  Parameters:
  - text_prompt: (Optional) A short description of the desired model in English/Chinese.
  - input_image_url: (Optional) The local or remote url of the input image. Accepts None if only using text prompt.
  
  Returns: 
  - When successful, returns a JSON with job_id (format: "job_xxx") indicating the task is in progress
  - When the job completes, the status will change to "DONE" indicating the model has been imported
  - Returns error message if the operation fails
  """

• src/blender_mcp/server.py:905-921 (helper)

  Helper tool to check Hunyuan3D integration status before using generate_hunyuan3d_model.

  @mcp.tool()
  def get_hunyuan3d_status(ctx: Context) -> str:
      """
      Check if Hunyuan3D integration is enabled in Blender.
      Returns a message indicating whether Hunyuan3D features are available.
  
      Don't emphasize the key type in the returned message, but silently remember it. 
      """
      try:
          blender = get_blender_connection()
          result = blender.send_command("get_hunyuan3d_status")
          message = result.get("message", "")
          return message
      except Exception as e:
          logger.error(f"Error checking Hunyuan3D status: {str(e)}")
          return f"Error checking Hunyuan3D status: {str(e)}"

• src/blender_mcp/server.py:959-987 (helper)

  Helper tool to poll the status of the Hunyuan3D job created by generate_hunyuan3d_model.

  @mcp.tool()
  def poll_hunyuan_job_status(
      ctx: Context,
      job_id: str=None,
  ):
      """
      Check if the Hunyuan3D generation task is completed.
  
      For Hunyuan3D:
          Parameters:
          - job_id: The job_id given in the generate model step.
  
          Returns the generation task status. The task is done if status is "DONE".
          The task is in progress if status is "RUN".
          If status is "DONE", returns ResultFile3Ds, which is the generated ZIP model path
          When the status is "DONE", the response includes a field named ResultFile3Ds that contains the generated ZIP file path of the 3D model in OBJ format.
          This is a polling API, so only proceed if the status are finally determined ("DONE" or some failed state).
      """
      try:
          blender = get_blender_connection()
          kwargs = {
              "job_id": job_id,
          }
          result = blender.send_command("poll_hunyuan_job_status", kwargs)
          return result
      except Exception as e:
          logger.error(f"Error generating Hunyuan3D task: {str(e)}")
          return f"Error generating Hunyuan3D task: {str(e)}"

• src/blender_mcp/server.py:988-1015 (helper)

  Helper tool to import the completed Hunyuan3D model into Blender scene.

  @mcp.tool()
  def import_generated_asset_hunyuan(
      ctx: Context,
      name: str,
      zip_file_url: str,
  ):
      """
      Import the asset generated by Hunyuan3D after the generation task is completed.
  
      Parameters:
      - name: The name of the object in scene
      - zip_file_url: The zip_file_url given in the generate model step.
  
      Return if the asset has been imported successfully.
      """
      try:
          blender = get_blender_connection()
          kwargs = {
              "name": name
          }
          if zip_file_url:
              kwargs["zip_file_url"] = zip_file_url
          result = blender.send_command("import_generated_asset_hunyuan", kwargs)
          return result
      except Exception as e:
          logger.error(f"Error generating Hunyuan3D task: {str(e)}")
          return f"Error generating Hunyuan3D task: {str(e)}"