BlenderMCP

Instructions

Implementation Reference

• src/blender_mcp/server.py:603-679 (handler)

  The core handler function for the 'search_sketchfab_models' tool. It is decorated with @mcp.tool() for registration and @telemetry_tool for logging. The function sends a 'search_sketchfab_models' command to the Blender addon with the provided parameters, processes the response, handles errors, and formats a readable list of matching models including name, UID, author, license, face count, and download status.

  @telemetry_tool("search_sketchfab_models")
  @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:612-622 (schema)

  The docstring provides the input schema (parameters description) and output description for the tool.

  """
  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:604-604 (registration)

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

  @mcp.tool()

• src/blender_mcp/server.py:1031-1037 (helper)

  Usage guidance for the tool within the asset_creation_strategy prompt.

  Sketchfab is good at Realistic models, and has a wider variety of models than PolyHaven.
  Use get_sketchfab_status() to verify its status
  If Sketchfab is enabled:
  - 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