get_viewport_screenshot

Capture screenshots of the Blender 3D viewport for documentation, progress tracking, or sharing visual updates during modeling workflows.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`max_size`	No

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

BlenderMCP