BlenderMCP

Instructions

Implementation Reference

• src/blender_mcp/server.py:335-365 (handler)

  The handler function decorated with @mcp.tool() that implements the get_polyhaven_categories tool. It proxies the request to the Blender addon socket server, checks if PolyHaven is enabled, formats and returns the list of categories sorted by asset count.
  @mcp.tool() def get_polyhaven_categories(ctx: Context, asset_type: str = "hdris") -> str: """ Get a list of categories for a specific asset type on Polyhaven. Parameters: - asset_type: The type of asset to get categories for (hdris, textures, models, all) """ try: blender = get_blender_connection() if not _polyhaven_enabled: return "PolyHaven integration is disabled. Select it in the sidebar in BlenderMCP, then run it again." result = blender.send_command("get_polyhaven_categories", {"asset_type": asset_type}) if "error" in result: return f"Error: {result['error']}" # Format the categories in a more readable way categories = result["categories"] formatted_output = f"Categories for {asset_type}:\n\n" # Sort categories by count (descending) sorted_categories = sorted(categories.items(), key=lambda x: x[1], reverse=True) for category, count in sorted_categories: formatted_output += f"- {category}: {count} assets\n" return formatted_output except Exception as e: logger.error(f"Error getting Polyhaven categories: {str(e)}") return f"Error getting Polyhaven categories: {str(e)}"
• src/blender_mcp/server.py:335-335 (registration)

  The @mcp.tool() decorator registers the get_polyhaven_categories function as an MCP tool.
  @mcp.tool()
• src/blender_mcp/server.py:337-342 (schema)

  Docstring providing the tool description and input parameter schema for automatic schema generation in FastMCP.
  """ Get a list of categories for a specific asset type on Polyhaven. Parameters: - asset_type: The type of asset to get categories for (hdris, textures, models, all) """
• src/blender_mcp/server.py:209-252 (helper)

  Helper function get_blender_connection() that manages the persistent socket connection to Blender and checks/updates PolyHaven enabled status, used by the tool handler.
  def get_blender_connection(): """Get or create a persistent Blender connection""" global _blender_connection, _polyhaven_enabled # Add _polyhaven_enabled to globals # If we have an existing connection, check if it's still valid if _blender_connection is not None: try: # First check if PolyHaven is enabled by sending a ping command result = _blender_connection.send_command("get_polyhaven_status") # Store the PolyHaven status globally _polyhaven_enabled = result.get("enabled", False) return _blender_connection except Exception as e: # Connection is dead, close it and create a new one logger.warning(f"Existing connection is no longer valid: {str(e)}") try: _blender_connection.disconnect() except: pass _blender_connection = None # Create a new connection if needed if _blender_connection is None: host = os.getenv("BLENDER_HOST", DEFAULT_HOST) port = int(os.getenv("BLENDER_PORT", DEFAULT_PORT)) _blender_connection = BlenderConnection(host=host, port=port) if not _blender_connection.connect(): logger.error("Failed to connect to Blender") _blender_connection = None raise Exception("Could not connect to Blender. Make sure the Blender addon is running.") logger.info("Created new persistent connection to Blender") return _blender_connection @mcp.tool() def get_scene_info(ctx: Context) -> str: """Get detailed information about the current Blender scene""" try: blender = get_blender_connection() result = blender.send_command("get_scene_info") # Just return the JSON representation of what Blender sent us return json.dumps(result, indent=2)