BlenderMCP

Instructions

Implementation Reference

• src/blender_mcp/server.py:270-311 (handler)

  The main handler function for the 'get_viewport_screenshot' tool. It connects to the Blender addon, sends the screenshot command with max_size parameter, saves to a temporary PNG file, reads the image bytes, cleans up the file, and returns an MCP Image object.

  @mcp.tool()
  def get_viewport_screenshot(ctx: Context, max_size: int = 800) -> Image:
      """
      Capture a screenshot of the current Blender 3D viewport.
      
      Parameters:
      - max_size: Maximum size in pixels for the largest dimension (default: 800)
      
      Returns the screenshot as an Image.
      """
      try:
          blender = get_blender_connection()
          
          # Create temp file path
          temp_dir = tempfile.gettempdir()
          temp_path = os.path.join(temp_dir, f"blender_screenshot_{os.getpid()}.png")
          
          result = blender.send_command("get_viewport_screenshot", {
              "max_size": max_size,
              "filepath": temp_path,
              "format": "png"
          })
          
          if "error" in result:
              raise Exception(result["error"])
          
          if not os.path.exists(temp_path):
              raise Exception("Screenshot file was not created")
          
          # Read the file
          with open(temp_path, 'rb') as f:
              image_bytes = f.read()
          
          # Delete the temp file
          os.remove(temp_path)
          
          return Image(data=image_bytes, format="png")
          
      except Exception as e:
          logger.error(f"Error capturing screenshot: {str(e)}")
          raise Exception(f"Screenshot failed: {str(e)}")

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

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

  @mcp.tool()

• src/blender_mcp/server.py:271-279 (schema)

  The function signature and docstring define the tool's input schema (ctx: Context, max_size: int = 800) and output (Image).

  def get_viewport_screenshot(ctx: Context, max_size: int = 800) -> Image:
      """
      Capture a screenshot of the current Blender 3D viewport.
      
      Parameters:
      - max_size: Maximum size in pixels for the largest dimension (default: 800)
      
      Returns the screenshot as an Image.
      """

• src/blender_mcp/server.py:206-237 (helper)

  Helper function used by the tool to obtain a persistent socket connection to the Blender addon server.

  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:
          _blender_connection = BlenderConnection(host="localhost", port=9876)
          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