search_sketchfab_models

Instructions

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.

Implementation Reference

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

  The @mcp.tool()-decorated handler function implementing the search_sketchfab_models tool. It proxies the search to a Blender connection via send_command and formats the retrieved model results into a human-readable list, including 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:583-600 (schema)

  Input schema defined by function parameters and docstring: query (str, required), categories (str, optional), count (int, default 20), downloadable (bool, default True); returns formatted str list of models.

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

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

  The tool is registered via the @mcp.tool() decorator on the handler function.

  @mcp.tool()

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

  The asset_creation_strategy prompt recommends using 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
          - 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
  """