search_sketchfab_models

Instructions

Implementation Reference

• src/blender_mcp/server.py:582-658 (handler)

  MCP tool handler for searching Sketchfab models. Connects to Blender, sends search command with parameters, handles errors, and formats the list of models with details like name, UID, author, license, face count, and downloadability.

  @mcp.tool()
  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:590-600 (schema)

  Input schema and documentation for the search_sketchfab_models tool, defining parameters query (str), categories (str optional), count (int default 20), downloadable (bool default True), and output as formatted 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.
  """

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

  Registration of the tool via the @mcp.tool() decorator.

  @mcp.tool()

• src/blender_mcp/server.py:896-897 (helper)

  Usage instruction in the asset_creation_strategy prompt recommending search_sketchfab_models for finding Sketchfab models.

  - For objects/models: First search using search_sketchfab_models() with your query
  - Then download specific models using download_sketchfab_model() with the UID