BlenderMCP

Instructions

Implementation Reference

• src/blender_mcp/server.py:659-701 (handler)

  The core handler function for the 'download_sketchfab_model' tool. It is decorated with @mcp.tool() for registration and implements the logic by sending a socket command to the Blender addon with the model UID, then parsing and returning the result.

  @mcp.tool()
  def download_sketchfab_model(
      ctx: Context,
      uid: str
  ) -> str:
      """
      Download and import a Sketchfab model by its UID.
      
      Parameters:
      - uid: The unique identifier of the Sketchfab model
      
      Returns a message indicating success or failure.
      The model must be downloadable and you must have proper access rights.
      """
      try:
          
          blender = get_blender_connection()
          logger.info(f"Attempting to download Sketchfab model with UID: {uid}")
          
          result = blender.send_command("download_sketchfab_model", {
              "uid": uid
          })
          
          if result is None:
              logger.error("Received None result from Sketchfab download")
              return "Error: Received no response from Sketchfab download request"
              
          if "error" in result:
              logger.error(f"Error from Sketchfab download: {result['error']}")
              return f"Error: {result['error']}"
          
          if result.get("success"):
              imported_objects = result.get("imported_objects", [])
              object_names = ", ".join(imported_objects) if imported_objects else "none"
              return f"Successfully imported model. Created objects: {object_names}"
          else:
              return f"Failed to download model: {result.get('message', 'Unknown error')}"
      except Exception as e:
          logger.error(f"Error downloading Sketchfab model: {str(e)}")
          import traceback
          logger.error(traceback.format_exc())
          return f"Error downloading Sketchfab model: {str(e)}"

• src/blender_mcp/server.py:664-672 (schema)

  Input/output schema and description provided in the function docstring, defining the 'uid' parameter as required string input.

  """
  Download and import a Sketchfab model by its UID.
  
  Parameters:
  - uid: The unique identifier of the Sketchfab model
  
  Returns a message indicating success or failure.
  The model must be downloadable and you must have proper access rights.
  """

• src/blender_mcp/server.py:659-659 (registration)

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

  @mcp.tool()

• src/blender_mcp/server.py:583-658 (helper)

  Companion 'search_sketchfab_models' tool used to find model UIDs before downloading with download_sketchfab_model.

  def search_sketchfab_models(
      ctx: Context,
      query: str,
      categories: str = None,
      count: int = 20,
      downloadable: bool = True
  ) -> str:
      """
      Search for models on Sketchfab with optional filtering.
      
      Parameters:
      - query: Text to search for
      - categories: Optional comma-separated list of categories
      - count: Maximum number of results to return (default 20)
      - downloadable: Whether to include only downloadable models (default True)
      
      Returns a formatted list of matching models.
      """
      try:
          
          blender = get_blender_connection()
          logger.info(f"Searching Sketchfab models with query: {query}, categories: {categories}, count: {count}, downloadable: {downloadable}")
          result = blender.send_command("search_sketchfab_models", {
              "query": query,
              "categories": categories,
              "count": count,
              "downloadable": downloadable
          })
          
          if "error" in result:
              logger.error(f"Error from Sketchfab search: {result['error']}")
              return f"Error: {result['error']}"
          
          # Safely get results with fallbacks for None
          if result is None:
              logger.error("Received None result from Sketchfab search")
              return "Error: Received no response from Sketchfab search"
              
          # Format the results
          models = result.get("results", []) or []
          if not models:
              return f"No models found matching '{query}'"
              
          formatted_output = f"Found {len(models)} models matching '{query}':\n\n"
          
          for model in models:
              if model is None:
                  continue
                  
              model_name = model.get("name", "Unnamed model")
              model_uid = model.get("uid", "Unknown ID")
              formatted_output += f"- {model_name} (UID: {model_uid})\n"
              
              # Get user info with safety checks
              user = model.get("user") or {}
              username = user.get("username", "Unknown author") if isinstance(user, dict) else "Unknown author"
              formatted_output += f"  Author: {username}\n"
              
              # Get license info with safety checks
              license_data = model.get("license") or {}
              license_label = license_data.get("label", "Unknown") if isinstance(license_data, dict) else "Unknown"
              formatted_output += f"  License: {license_label}\n"
              
              # Add face count and downloadable status
              face_count = model.get("faceCount", "Unknown")
              is_downloadable = "Yes" if model.get("isDownloadable") else "No"
              formatted_output += f"  Face count: {face_count}\n"
              formatted_output += f"  Downloadable: {is_downloadable}\n\n"
          
          return formatted_output
      except Exception as e:
          logger.error(f"Error searching Sketchfab models: {str(e)}")
          import traceback
          logger.error(traceback.format_exc())
          return f"Error searching Sketchfab models: {str(e)}"

• src/blender_mcp/server.py:564-581 (helper)

  Helper tool to check if Sketchfab integration (required for download_sketchfab_model) is enabled.

  @mcp.tool()
  def get_sketchfab_status(ctx: Context) -> str:
      """
      Check if Sketchfab integration is enabled in Blender.
      Returns a message indicating whether Sketchfab features are available.
      """
      try:
          blender = get_blender_connection()
          result = blender.send_command("get_sketchfab_status")
          enabled = result.get("enabled", False)
          message = result.get("message", "")
          if enabled:
              message += "Sketchfab is good at Realistic models, and has a wider variety of models than PolyHaven."        
          return message
      except Exception as e:
          logger.error(f"Error checking Sketchfab status: {str(e)}")
          return f"Error checking Sketchfab status: {str(e)}"