Query current Blender scene hierarchy, objects list, materials, and world settings.

Returns complete scene metadata including all objects, their types, transforms, materials, and collections.

Args:

• response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: For JSON: { objects: [...], materials: [...], collections: [...], world: {...} } For markdown: Formatted hierarchy with object details

Use when: Need to understand current scene state, find object names, or verify scene setup Don't use when: Modifying scene (use create/modify tools instead)

Query detailed properties of specific Blender object by name.

Returns object type, transforms (location/rotation/scale), bounding box, materials, modifiers, and parent/children relationships.

Args:

• object_name (string): Name of object to query (e.g., "Cube", "Camera")

• response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: For JSON: { name, type, location: [x,y,z], rotation: [...], scale: [...], materials: [...], ... } For markdown: Formatted object details

Use when: Need specific object details before modifying Don't use when: Querying entire scene (use blender_get_scene_info instead)

Error: Returns "Object not found" if object_name doesn't exist

Create basic 3D primitive object in Blender scene.

Creates mesh primitive at specified location with optional custom name and scale.

Args:

• primitive_type: 'CUBE' | 'SPHERE' | 'CYLINDER' | 'CONE' | 'TORUS' | 'PLANE' | 'MONKEY' | 'UV_SPHERE' | 'ICO_SPHERE'

• name (optional): Custom object name (default: auto-generated)

• location (optional): Position [x, y, z] (default: [0, 0, 0])

• scale (optional): Scale [x, y, z] (default: [1, 1, 1])

Returns: Success message with created object name

Examples:

• Create cube at origin: { primitive_type: "CUBE" }

• Create sphere at (5, 0, 2): { primitive_type: "SPHERE", location: [5, 0, 2] }

Use when: Starting new scene, adding basic geometry Don't use when: Need complex custom geometry (use execute_blender_code instead)

Modify transforms of existing Blender object.

Update location, rotation (in radians), and/or scale of object by name.

Args:

• object_name (string): Object to modify

• location (optional): New position [x, y, z]

• rotation (optional): New rotation in radians [x, y, z]

• scale (optional): New scale [x, y, z]

At least one transform property must be provided.

Returns: Success message with updated properties

Use when: Positioning, rotating, or scaling existing objects Don't use when: Creating new objects (use create_primitive instead)

Delete object from Blender scene by name.

Permanently removes object and its data. Cannot be undone via MCP.

Args:

• object_name (string): Object to delete

Returns: Success confirmation

Use when: Cleaning up scene, removing unwanted objects Don't use when: Temporarily hiding objects (no hide functionality in MCP currently)

Error: "Object not found" if object doesn't exist

Create PBR material with Principled BSDF shader.

Creates material with standard PBR properties. Use Principled BSDF workflow.

Args:

• material_name: Material name

• base_color (optional): RGBA [r, g, b, a] with 0-1 values

• metallic (optional): 0-1, default 0

• roughness (optional): 0-1, default 0.5

• emission_color (optional): RGBA for emission

• emission_strength (optional): Emission intensity

Returns: Success message

Example: { material_name: "RedMetal", base_color: [0.8, 0.1, 0.1, 1], metallic: 1, roughness: 0.2 }

Apply existing material to Blender object.

Assigns material to object's active material slot. Object must exist and material must be created first.

Args:

• object_name (string): Object to apply material to

• material_name (string): Material to apply

Returns: Success confirmation

Use when: Texturing objects after creating materials Don't use when: Material doesn't exist (create it first)

Modify specific property of existing material.

Updates PBR material properties like color, metallic, roughness, or emission.

Args:

• material_name (string): Material to modify

• property: 'base_color' | 'metallic' | 'roughness' | 'emission_color' | 'emission_strength'

• value: Property value (color as RGBA array or number for metallic/roughness/strength)

Returns: Success confirmation

Examples:

• Make metallic: { material_name: "Metal", property: "metallic", value: 1.0 }

• Set red color: { material_name: "Red", property: "base_color", value: [1, 0, 0, 1] }

Capture current viewport as base64 image.

Takes screenshot of current 3D viewport view. Limited to 800px max dimension for performance.

Args:

• max_size (optional): Maximum dimension in pixels (100-800, default: 800)

Returns: Base64 encoded PNG image data with metadata

Use when: Visualizing scene state, checking results, debugging Don't use when: Need high resolution renders (use Blender render instead)

Performance: Larger images take longer to process and transfer

Execute Python code using Blender's bpy API.

Provides escape hatch for complex operations not covered by other tools. Use full bpy API access.

Args:

• code (string): Python code to execute using bpy API (max 100KB)

• timeout (optional): Execution timeout in milliseconds (1000-180000, default: 180000)

Returns: Execution result with any output or error message

Examples:

• List objects: [obj.name for obj in bpy.data.objects]

• Create custom mesh: bpy.ops.mesh.primitive_cube_add(location=(1, 2, 3))

• Get object location: bpy.data.objects['Cube'].location[:]

Use when: Complex operations, custom workflows, bpy API access Don't use when: Simple operations covered by dedicated tools

Security: Code is validated for dangerous patterns. System commands are restricted. Performance: Long-running code may hit timeout limits (default 3 minutes)

Create a new Blender collection for organizing assets.

Collections in Blender help organize scenes by grouping related objects. Collections can be nested for hierarchical organization.

Args:

• name (string): Collection name (alphanumeric, spaces, hyphens, underscores, max 64 chars)

• parent_collection (optional): Parent collection name for nested organization

Returns: Collection creation confirmation and collection information

Examples:

• Create main collection: name="Environment"

• Nested collection: name="Trees", parent_collection="Environment"

• Asset library: name="Props", parent_collection="Library"

Use when: Organizing scene assets, creating asset libraries, structuring complex scenes Don't use when: Creating single objects without organization needs

Performance: Instant operation, negligible performance impact

Move or copy an object to a specific collection.

Objects in Blender can belong to multiple collections. This tool provides flexible asset organization and scene management.

Args:

• object_name (string): Target object name to add to collection

• collection_name (string): Destination collection name

• remove_from_others (boolean, default false): Remove from other collections

Returns: Collection assignment confirmation and updated object information

Examples:

• Move object: object_name="TreeOak", collection_name="Trees", remove_from_others=true

• Add to multiple: object_name="Rock", collection_name="Environment", remove_from_others=false

• Organize assets: object_name="Character", collection_name="Characters"

Use when: Organizing scene assets, managing object relationships, structuring workflow Don't use when: Creating new objects (use object creation tools instead)

Performance: Instant operation, negligible performance impact

List all collections in the current Blender scene with optional object details.

Provides comprehensive view of scene organization structure, including nested collections and object membership.

Args:

• include_objects (boolean, default false): Include objects in each collection

• object_details (boolean, default false): Include detailed object information

Returns: Hierarchical list of collections with optional object details and statistics

Examples:

• Simple list: include_objects=false, object_details=false

• With objects: include_objects=true, object_details=false

• Full details: include_objects=true, object_details=true

Use when: Understanding scene structure, managing assets, planning organization Don't use when: Creating new collections (use create_collection instead)

Performance: Fast operation, minimal performance impact

Automatically organize scene assets into collections based on object type.

This intelligent organization tool creates collections for different asset types (models, materials, etc.) and moves objects accordingly.

Args:

• create_collections (boolean, default true): Create collections for each asset type

• existing_objects_only (boolean, default true): Only organize existing objects

• prefix_with_type (boolean, default false): Prefix object names with asset type

Returns: Organization summary with collections created and objects moved

Examples:

• Basic organization: create_collections=true, existing_objects_only=true, prefix_with_type=false

• Include new objects: create_collections=true, existing_objects_only=false

• Naming convention: create_collections=true, prefix_with_type=true

Use when: Cleaning up disorganized scenes, establishing asset workflows, improving scene management Don't use when: Fine-grained manual control needed, complex custom organization

Performance: Moderate impact depending on scene size and object count

List files and directories in the Blender project or specified directory.

Provides comprehensive file system overview for project management and asset organization.

Args:

• directory_path (optional): Directory path to list (relative to project)

• recursive (boolean, default false): Include subdirectories recursively

• include_hidden (boolean, default false): Include hidden files and directories

Returns: File listing with metadata including sizes, types, and modification times

Examples:

• Current directory: directory_path="", recursive=false

• Recursive list: directory_path="assets", recursive=true

• Include hidden: directory_path=".", include_hidden=true

Use when: Project organization, asset management, file system navigation Don't use when: Creating new files or directories (use create_directory/save_file)

Performance: Fast operation, minor impact with large recursive listings

Security: Only accesses files within project directory structure

Create a new directory within the Blender project structure.

Useful for organizing assets, creating project folders, and establishing file system structure.

Args:

• directory_path (string): Directory path to create (relative to project)

• parent_directories (boolean, default true): Create parent directories if needed

Returns: Directory creation confirmation and path information

Examples:

• Asset folder: directory_path="assets/models"

• Textures: directory_path="assets/textures"

• Project structure: directory_path="scenes/environment"

Use when: Setting up project structure, organizing assets, creating workflow folders Don't use when: Creating files (use save_file instead)

Performance: Instant operation, negligible performance impact

Security: Only creates directories within project boundary

Save base64 encoded file data to the Blender project directory.

Supports saving various file types including assets, textures, and project files.

Args:

• file_path (string): Destination file path (relative to project)

• data (string): Base64 encoded file data

• overwrite (boolean, default false): Overwrite existing file

Returns: File save confirmation with size and type information

Examples:

• Save texture: file_path="assets/textures/wood.png", data="[base64]"

• Save model: file_path="assets/models/chair.fbx", data="[base64]"

• Save project: file_path="scenes/level1.blend", data="[base64]"

Use when: Saving downloaded assets, exporting files, project file management Don't use when: Creating files from Blender operations (use Blender export tools)

Performance: Depends on file size, typically fast for assets under 100MB

Security: Validates file paths and saves within project directory

Download file from URL and save to Blender project directory.

Supports downloading assets, textures, and reference materials from external sources.

Args:

• url (string): URL to download from

• destination_path (string): Destination file path (relative to project)

• timeout (number, default 30000): Download timeout in milliseconds

Returns: Download confirmation with file size, type, and save location

Examples:

• Download texture: url="https://example.com/texture.jpg", destination_path="assets/textures/download.jpg"

• Download model: url="https://example.com/model.fbx", destination_path="assets/models/download.fbx"

• Reference image: url="https://example.com/ref.png", destination_path="references/ref.png"

Use when: Downloading external assets, reference materials, textures from web Don't use when: Accessing local files (use save_file with local data)

Performance: Depends on file size and network speed, timeout protection included

Security: Validates URLs, enforces timeouts, saves within project directory

Import external 3D assets into Blender scene with comprehensive options.

Supports multiple 3D file formats including FBX, OBJ, GLTF, and more with advanced import options.

Args:

• file_path (string): Path to asset file to import (relative to project)

• format (optional): Asset format (auto-detected if not specified)

• options (optional): Import options including location, rotation, scale, and processing

Returns: Import confirmation with object details and processing information

Examples:

• Basic import: file_path="assets/models/chair.fbx"

• With positioning: file_path="assets/tree.obj", options={location: [0, 0, 0]}

• Optimized import: file_path="assets/vehicle.gltf", options={decimate: true, decimate_ratio: 0.5}

Use when: Adding external assets to scenes, importing models/textures, asset workflows Don't use when: Creating new primitives (use object creation tools instead)

Performance: Varies by file size and complexity, typically 1-10 seconds for most assets

Export Blender objects or entire scene to various 3D formats.

Comprehensive export tool with support for multiple formats and export options including materials and animations.

Args:

• objects (optional): Object names to export (exports all if not specified)

• format (enum): Export format (fbx, obj, gltf, glb, stl, ply, abc)

• file_path (string): Export destination path (relative to project)

• options (optional): Export options including modifiers, materials, and compression

Returns: Export confirmation with file size, format, and object count

Examples:

• Export all: format="fbx", file_path="exports/scene.fbx"

• Export specific: objects=["Cube", "Sphere"], format="obj", file_path="exports/selection.obj"

• Optimized export: format="gltf", file_path="exports/optimized.glb", options={compression: 90}

Use when: Sharing assets, exporting for other applications, backup and version control Don't use when: Quick previews (use screenshot tools instead)

Performance: Varies by scene complexity and format, typically 5-30 seconds

List all supported file formats for import and export operations.

Provides comprehensive format information with capabilities and recommended use cases.

Args:

• operation (enum): Filter by operation type (import, export, both)

Returns: Detailed list of supported formats with capabilities and use cases

Examples:

• All formats: operation="both"

• Import only: operation="import"

• Export only: operation="export"

Use when: Planning asset workflows, choosing formats, understanding capabilities Don't use when: Actual import/export operations (use import_asset/export_asset instead)

Performance: Instant operation, negligible performance impact

Optimize 3D assets for better performance through mesh decimation and cleanup.

Reduces polygon count and optimizes geometry while preserving visual quality and essential attributes.

Args:

• objects (array): Object names to optimize

• target_poly_count (optional): Target polygon count (100-1000000)

• decimation_ratio (optional): Decimation ratio (0.1-1.0)

• preserve_uvs (boolean, default true): Preserve UV coordinates

• preserve_materials (boolean, default true): Preserve material assignments

• preserve_vertex_colors (boolean, default true): Preserve vertex colors

Returns: Optimization summary with before/after statistics and performance improvements

Examples:

• Target count: objects=["HighPolyModel"], target_poly_count=10000

• Ratio based: objects=["Tree"], decimation_ratio=0.3

• Multiple objects: objects=["Rock1", "Rock2", "Rock3"], decimation_ratio=0.5

Use when: Optimizing for real-time applications, reducing file sizes, performance improvements Don't use when: Preserving maximum detail for rendering (use export with high quality instead)

Performance: Moderate impact depending on mesh complexity, typically 5-60 seconds

Search the PolyHaven library for free 3D assets, textures, and HDRIs.

PolyHaven offers 10,000+ free CC0-licensed 3D assets including models, materials, textures, and HDRIs.

Args:

• query (optional): Search query for assets

• type (optional): Asset type filter (model, material, texture, hdri)

• limit (integer): Maximum number of results (1-100, default 20)

• quality (optional): Quality level for thumbnails

• tags (optional): Filter by tags array

Returns: Search results with asset metadata, thumbnails, and download options

Examples:

• Wood textures: query="wood", type="texture", limit=10

• Tree models: query="tree", type="model", limit=5

• HDRI skies: type="hdri", limit=8

• Popular materials: type="material", limit=15

Use when: Finding reference assets, texture sourcing, environment creation Don't use when: Downloading specific assets (use download_polyhaven_asset instead)

Performance: Network-dependent, typically 1-5 seconds

License: All PolyHaven assets are CC0 (public domain)

Download a PolyHaven asset and optionally import it directly into Blender.

Downloads high-quality assets from PolyHaven with automatic file management and scene integration.

Args:

• asset_id (string): PolyHaven asset ID to download

• quality (enum): Download quality level (hd, 1k, 2k, 4k, 8k)

• save_path (optional): Save path (relative to project assets directory)

• import_to_scene (boolean, default true): Import directly into Blender scene

• import_options (optional): Import options if importing to scene

Returns: Download confirmation with file information and import status

Examples:

• Download 2K texture: asset_id="old_wood_01", quality="2k"

• Download and import model: asset_id="oak_tree", quality="4k", import_to_scene=true

• Custom save path: asset_id="sky_cloudy", quality="hdr", save_path="environments/sky.hdr"

Use when: Adding professional assets to scenes, sourcing textures, environment setup Don't use when: Just browsing assets (use search_polyhaven instead)

Performance: Network and file-size dependent, typically 5-60 seconds

Security: Validates asset IDs, downloads to secure project directory

Get detailed information about a specific PolyHaven asset.

Provides comprehensive asset metadata including download options, technical specifications, and licensing information.

Args:

• asset_id (string): PolyHaven asset ID to get details for

• include_thumbnails (boolean, default true): Include thumbnail information

Returns: Complete asset metadata with download options, file sizes, and quality levels

Examples:

• Basic details: asset_id="old_wood_01"

• With thumbnails: asset_id="oak_tree", include_thumbnails=true

• Check availability: asset_id="sky_cloudy"

Use when: Verifying asset availability, checking download options, asset metadata research Don't use when: Downloading assets (use download_polyhaven_asset instead)

Performance: Fast network request, typically 1-3 seconds

License: Returns CC0 licensing information for all assets

Get trending and popular assets from PolyHaven.

Returns the most downloaded and highly-rated assets across different categories.

Args:

• type (optional): Asset type filter (model, material, texture, hdri)

• limit (integer): Maximum number of results (1-100, default 20)

• quality (optional): Quality level for thumbnails

Returns: List of popular assets with download counts and ratings

Examples:

• Popular models: type="model", limit=10

• Trending textures: type="texture", limit=15

• Top HDRIs: type="hdri", limit=5

• All categories: limit=20

Use when: Discovering trending assets, finding high-quality content, asset inspiration Don't use when: Searching for specific criteria (use search_polyhaven instead)

Performance: Fast network request, typically 1-3 seconds

Content: Updated daily based on community downloads and ratings