Skip to main content
Glama

Blender MCP

CI CD Latest release License: MIT Python uv Blender MCP Local only

Production-oriented Model Context Protocol (MCP) integration for Blender. AI clients (Claude Desktop, Cursor, VS Code, Codex, Windsurf, and others) can inspect scenes, model, shade, light, render, and visually verify work through a local bridge.

This project is not affiliated with the Blender Foundation.

Features

  • MCP stdio server + Blender addon TCP bridge (localhost by default)

  • Scene inspection, object/mesh modeling, materials, modifiers, cameras, lights

  • Geometry Nodes helpers with socket inspection

  • Viewport screenshots and render previews for visual verification

  • Animation keyframes, import/export, project save/load

  • Optional asset providers (Poly Haven, Sketchfab, Poly Pizza, AI 3D stubs)

  • Script execution with explicit permission modes (restricted / confirmation / trusted)

  • Auth token, path allow-lists, render limits, tool-group toggles

Related MCP server: SandBase MCP

Prerequisites

  • uv (required)

  • Blender 3.6+ (4.x recommended)

Quick start

Install site (Astro / GitHub Pages): axcel-blade.github.io/Blender-MCP

Windows (PowerShell) — one liner:

irm https://axcel-blade.github.io/Blender-MCP/install.ps1 | iex

macOS / Linux:

curl -LsSf https://axcel-blade.github.io/Blender-MCP/install.sh | sh

Or from a local clone with uv:

uv sync
uv run blender-mcp install-addon
  1. Blender → Edit → Preferences → Add-ons → enable Blender MCP

  2. 3D Viewport → press N → AI / MCP → Start

  3. Point your MCP client at:

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["run", "--directory", "C:/path/to/Blender-MCP", "blender-mcp"]
    }
  }
}

Documentation

Document

Purpose

docs/ARCHITECTURE.md

System design

docs/INSTALLATION.md

Install & MCP client setup

docs/CONFIGURATION.md

Config & environment

docs/TOOLS.md

MCP tools overview

docs/SECURITY.md

Technical security controls

docs/TROUBLESHOOTING.md

Common failures

CHANGELOG.md

Version history

CONTRIBUTING.md

Git Flow & contribution guide

SUPPORT.md

How to get help

SECURITY.md

Vulnerability reporting

CODE_OF_CONDUCT.md

Community standards

LICENSE

MIT license

Architecture

AI Client --stdio MCP--> blender-mcp server --TCP NDJSON--> Blender addon --bpy--> Blender

See docs/ARCHITECTURE.md.

Git Flow

Branch

Purpose

main

Production releases

develop

Integration

feature/*

Features → develop

release/*

Release prep → main + develop

hotfix/*

Urgent fixes from main

Details: CONTRIBUTING.md.

Security

  • Bridge binds to 127.0.0.1 unless remote mode is explicitly enabled

  • Optional shared auth token

  • execute_blender_code is not a sandbox — keep script_permission=restricted unless you trust the client

  • Path allow-lists for file operations when configured

Report vulnerabilities privately via SECURITY.md.

Development

This project is managed exclusively with uv (lockfile + virtualenv).

uv sync
uv run pytest
uv run ruff check src tests
uv run pyright

Diagnose a live Blender connection:

uv run blender-mcp diagnose

License

MIT © AXCEL BLADE — see LICENSE.

External asset providers retain their own licenses and attribution requirements.

Available Tools

156 tools
add_geometry_nodeC

Add a node to a geometry node group.

Inputs: node_type (required), group_name (required), node_name. Returns: object

add_modifierC

Add a modifier to an object.

Inputs: name (required), modifier_type (required), settings, modifier_name. Returns: object

animate_locationC

Keyframe object location.

Inputs: name (required), frame (required), location (required). Returns: object

animate_rotationC

Keyframe object rotation.

Inputs: name (required), frame (required), rotation (required). Returns: object

animate_scaleD

Keyframe object scale.

Inputs: name (required), frame (required), scale (required). Returns: object

apply_modifierD

Apply a modifier.

Inputs: name (required), modifier_name (required). Returns: object

apply_transformD

Apply object transform.

Inputs: name (required), scale, location, rotation. Returns: object

assign_materialC

Assign a material to an object.

Inputs: object_name (required), material_name (required), slot. Returns: object

assign_textureC

Assign an image texture to a material input.

Inputs: image_path (required), material_name (required), input_name. Returns: object

bevel_meshC

Bevel mesh edges.

Inputs: name (required), amount, segments. Returns: object

blender_mcp_versionA

Return Blender MCP server version and bridge configuration (no secrets).

Inputs: no named parameters.

camera_viewC

Return camera framing metadata for visual verification.

Inputs: name. Returns: object

capture_camera_viewC

Capture from the active or named camera.

Inputs: camera, max_size. Returns: object

capture_material_previewC

Capture a material preview viewport image.

Inputs: max_size. Returns: object

capture_multiple_anglesC

Capture multiple orthographic/perspective angles.

Inputs: angles, max_size. Returns: object

capture_renderC

Capture or return the latest render preview.

Inputs: max_size. Returns: object

capture_scene_previewC

Capture a scene preview image.

Inputs: max_size. Returns: object

capture_viewportC

Capture the viewport with optional view/shading overrides.

Inputs: view, shading, max_size. Returns: object

capture_wireframeC

Capture a wireframe viewport image.

Inputs: max_size. Returns: object

configure_camera_depth_of_fieldD

Configure camera depth of field.

Inputs: name (required), fstop, enabled, focus_object, +1 more. Returns: object

configure_camera_lensC

Configure camera lens settings.

Inputs: name (required), lens, type, ortho_scale. Returns: object

connect_geometry_nodesC

Connect two geometry nodes.

Inputs: to_node (required), from_node (required), to_socket (required), group_name (required), +1 more. Returns: object

create_animation_previewC

Capture frames for an animation preview strip.

Inputs: step, frame_end, frame_start. Returns: object

create_array_of_objectsC

Duplicate an object into an array along an offset.

Inputs: name (required), count, offset. Returns: object

create_basic_shaderC

Create a basic Principled material.

Inputs: name, color. Returns: object

create_cameraD

Create a camera.

Inputs: lens, name, location, rotation, +1 more. Returns: object

create_circleD

Create a circle.

Inputs: name, radius, location, vertices, +1 more. Returns: object

create_collectionD

Create a collection.

Inputs: name (required), parent. Returns: object

create_coneD

Create a cone.

Inputs: name, depth, radius1, radius2, +2 more. Returns: object

create_cubeC

Create a cube.

Inputs: name, size, location, collection. Returns: object

create_curveC

Create a Bezier curve.

Inputs: name, location, collection. Returns: object

create_cylinderD

Create a cylinder.

Inputs: name, depth, radius, location, +2 more. Returns: object

create_emission_materialC

Create an emission material.

Inputs: name, color, strength. Returns: object

create_emptyD

Create an empty.

Inputs: name, location, collection, empty_display_type. Returns: object

create_geometry_nodes_modifierC

Add a Geometry Nodes modifier.

Inputs: name (required), group_name. Returns: object

create_glass_materialD

Create a glass material.

Inputs: ior, name, roughness. Returns: object

create_hierarchyC

Create nested collections by path names.

Inputs: names (required). Returns: object

create_ico_sphereD

Create an icosphere.

Inputs: name, radius, location, collection, +1 more. Returns: object

create_keyframeC

Insert a keyframe on an object.

Inputs: name (required), data_path (required), frame, index. Returns: object

create_lightD

Create a light.

Inputs: name, color, energy, location, +1 more. Returns: object

create_lighting_setupC

Create a lighting preset (three_point, studio, product, outdoor, interior, cinematic).

Inputs: preset, target. Returns: object

create_materialC

Create a Principled BSDF material.

Inputs: name, metallic, roughness, base_color. Returns: object

create_meshC

Create an empty mesh object.

Inputs: name, location. Returns: object

create_metallic_materialD

Create a metallic material.

Inputs: name, color, roughness. Returns: object

create_node_groupC

Create a geometry node group.

Inputs: name. Returns: object

create_objectD

Create a generic object by type.

Inputs: object_type (required), name, scale, location, +2 more. Returns: object

create_planeD

Create a plane.

Inputs: name, size, location, collection. Returns: object

create_primitiveC

Create a mesh primitive (cube, uv_sphere, cylinder, ...).

Inputs: primitive (required), name, size, scale, +4 more. Returns: object

create_sphereD

Create a UV sphere.

Inputs: name, radius, location, collection. Returns: object

create_textC

Create a text object.

Inputs: name, text, location, collection. Returns: object

create_torusD

Create a torus.

Inputs: name, location, collection, major_radius, +1 more. Returns: object

create_transparent_materialC

Create a transparent material.

Inputs: name, alpha, color. Returns: object

create_uv_sphereC

Create a UV sphere with segment/ring control.

Inputs: name, rings, radius, location, +2 more. Returns: object

decimate_meshD

Decimate a mesh.

Inputs: name (required), ratio. Returns: object

delete_collectionD

Delete a collection.

Inputs: name (required), confirmed. Returns: object

delete_geometryC

Delete mesh geometry components.

Inputs: name (required), mode. Returns: object

delete_lightC

Delete a light object.

Inputs: name (required), confirmed. Returns: object

delete_objectB

Delete a single object (requires confirmed=true when confirm_destructive is on).

Inputs: name (required), confirmed. Returns: object

delete_objectsC

Delete multiple objects by explicit names.

Inputs: names (required), confirmed. Returns: object

diagnose_blender_connectionB

Diagnose MCP-to-Blender connectivity and capabilities.

Inputs: no named parameters. Returns: object

duplicate_objectD

Duplicate an object.

Inputs: name (required), linked, new_name. Returns: object

edit_meshC

Run a structured mesh edit operation on an object.

Inputs: name (required), operation (required), params. Returns: object

execute_blender_codeC

Execute Python code inside Blender when script permissions allow it.

    Warning: this is not a secure sandbox. It can access files, network, and
    system capabilities available to the Blender process.
    

Inputs: code (required), timeout, confirmed, preview_only. Returns: object

export_assetC

Export selected or named objects.

Inputs: path (required), objects, overwrite. Returns: object

export_sceneC

Export the full scene.

Inputs: path (required), overwrite. Returns: object

export_selected_objectsC

Export currently selected objects.

Inputs: path (required), overwrite. Returns: object

extrude_meshC

Extrude selected mesh geometry (object-mode helper).

Inputs: name (required), offset. Returns: object

fill_facesC

Fill selected boundary with faces where possible.

Inputs: name (required). Returns: object

focus_camera_on_objectC

Point/focus a camera at an object.

Inputs: camera (required), object_name (required). Returns: object

frame_objectsC

Frame objects in a camera view.

Inputs: camera, object_names. Returns: object

get_active_objectA

Return the active object, if any.

Inputs: no named parameters. Returns: object

get_animation_infoC

Summarize animation data and timeline.

Inputs: no named parameters. Returns: object

get_camera_infoC

Get camera information.

Inputs: name. Returns: object

get_collection_infoC

Get collection details.

Inputs: name (required). Returns: object

get_collectionsB

List collections in the scene.

Inputs: no named parameters. Returns: object

get_current_frameA

Get the current frame number.

Inputs: no named parameters. Returns: object

get_light_infoD

Get light information.

Inputs: name. Returns: object

get_lightsA

List lights in the scene.

Inputs: no named parameters. Returns: object

get_material_infoC

Inspect a material and its nodes.

Inputs: name (required). Returns: object

get_material_nodesC

List nodes in a material node tree.

Inputs: name (required). Returns: object

get_materialsB

List materials in the blend file.

Inputs: no named parameters. Returns: object

get_mesh_statisticsB

Get mesh statistics for an object or the whole scene.

Inputs: name. Returns: object

get_modifiersC

List modifiers on an object.

Inputs: name (required). Returns: object

get_node_socket_infoC

Get socket schema for a node.

Inputs: node_name (required), group_name (required). Returns: object

get_object_infoB

Get detailed info for a single object by name.

Inputs: name (required). Returns: object

get_objectsC

List objects with optional filtering and pagination.

Inputs: limit, offset, name_filter, object_type. Returns: object

get_object_transformC

Get location/rotation/scale for an object.

Inputs: name (required), space. Returns: object

get_project_pathB

Get the current blend file path.

Inputs: no named parameters. Returns: object

get_render_resultA

Return the last render result path/metadata.

Inputs: no named parameters. Returns: object

get_render_settingsC

Get render settings.

Inputs: no named parameters. Returns: object

get_scene_hierarchyB

Return the scene collection hierarchy.

Inputs: no named parameters. Returns: object

get_scene_infoC

Return detailed information about the current Blender scene.

Inputs: no named parameters. Returns: object

get_scene_settingsB

Get unit/frame/gravity and related scene settings.

Inputs: no named parameters. Returns: object

get_scene_summaryC

Return a compact summary of the current scene.

Inputs: no named parameters. Returns: object

get_selected_objectsB

List currently selected objects.

Inputs: no named parameters. Returns: object

get_viewport_screenshotC

Capture the 3D viewport as an image for visual verification.

Inputs: shading, max_size. Returns: object

import_assetC

Import a 3D asset (FBX/OBJ/STL/GLTF/GLB/USD/BLEND).

Inputs: path (required), collection. Returns: object

import_external_assetC

Download metadata/URLs then ask Blender to import when a local path is available.

Inputs: source (required), asset_id (required), asset_type, resolution. Returns: object

import_polyhaven_via_blenderB

Ask Blender to import a Poly Haven asset by id (addon-side download).

Inputs: asset_id (required), asset_type, resolution. Returns: object

inset_facesC

Inset faces on a mesh object.

Inputs: name (required), thickness. Returns: object

inspect_animationD

Inspect animation data.

Inputs: name. Returns: object

inspect_node_groupC

Inspect a node group structure.

Inputs: group_name (required). Returns: object

inspect_renderA

Return metadata about the latest captured/rendered image.

Inputs: no named parameters. Returns: object

join_objectsC

Join multiple mesh objects.

Inputs: names (required), target. Returns: object

list_asset_providersA

List configured asset providers and credential status (no secrets).

Inputs: no named parameters. Returns: object

list_geometry_node_typesA

List available geometry node type identifiers.

Inputs: no named parameters. Returns: object

list_materialsC

List all materials.

Inputs: no named parameters. Returns: object

list_modifiersC

List modifiers on an object with settings.

Inputs: name (required). Returns: object

merge_verticesC

Merge vertices by distance.

Inputs: name (required), distance. Returns: object

mesh_cleanupD

Run common mesh cleanup operations.

Inputs: name (required). Returns: object

modify_cameraD

Modify camera settings.

Inputs: name (required), settings (required). Returns: object

modify_lightD

Modify light settings.

Inputs: name (required), settings (required). Returns: object

modify_materialC

Modify Principled BSDF inputs on a material.

Inputs: name (required), settings (required). Returns: object

modify_modifierD

Update modifier settings.

Inputs: name (required), settings (required), modifier_name (required). Returns: object

modify_objectC

Modify common object properties.

Inputs: name (required), scale, location, rotation, +1 more. Returns: object

move_objectD

Move an object.

Inputs: name (required), location (required), space. Returns: object

move_object_to_collectionC

Move an object into a collection.

Inputs: collection (required), object_name (required), exclusive. Returns: object

open_blend_fileD

Open a .blend file.

Inputs: path (required). Returns: object

organize_sceneC

Organize objects into logical collections.

Inputs: structure. Returns: object

recalculate_normalsC

Recalculate mesh normals.

Inputs: name (required), inside. Returns: object

remesh_meshC

Apply remesh via modifier and apply it.

Inputs: name (required), mode, octree_depth. Returns: object

remove_keyframeC

Remove a keyframe.

Inputs: name (required), data_path (required), frame. Returns: object

remove_materialC

Remove a material slot from an object.

Inputs: object_name (required), slot. Returns: object

remove_modifierC

Remove a modifier from an object.

Inputs: name (required), modifier_name (required). Returns: object

rename_collectionD

Rename a collection.

Inputs: name (required), new_name (required). Returns: object

rename_objectC

Rename an object.

Inputs: name (required), new_name (required). Returns: object

render_animationC

Render an animation range.

Inputs: frame_end, frame_start, output_path. Returns: object

render_finalC

Render a higher-quality still.

Inputs: samples, output_path. Returns: object

render_previewC

Render a fast preview image.

Inputs: samples, resolution_percentage. Returns: object

render_sceneD

Render the current frame.

Inputs: engine, samples, output_path, write_still, +1 more. Returns: object

reset_transformC

Reset object transform channels.

Inputs: name (required), scale, location, rotation. Returns: object

rotate_objectC

Rotate an object (Euler radians).

Inputs: name (required), rotation (required), space. Returns: object

save_asC

Save the blend file to a new path.

Inputs: path (required), overwrite. Returns: object

save_blend_fileC

Save the current .blend file.

Inputs: path, overwrite. Returns: object

scale_objectD

Scale an object.

Inputs: name (required), scale (required). Returns: object

search_assetsC

Search external asset providers (polyhaven, sketchfab, polypizza).

Inputs: query (required), source (required), limit, asset_type. Returns: object

separate_objectsC

Separate a mesh object.

Inputs: name (required), mode. Returns: object

set_active_cameraC

Set the active scene camera.

Inputs: name (required). Returns: object

set_animation_rangeC

Set scene animation range.

Inputs: frame_end (required), frame_start (required). Returns: object

set_current_frameC

Set the current frame.

Inputs: frame (required). Returns: object

set_geometry_node_inputC

Set a geometry node input value.

Inputs: value (required), node_name (required), group_name (required), input_name (required). Returns: object

set_keyframeC

Set a property value and keyframe it.

Inputs: name (required), value (required), data_path (required), frame. Returns: object

set_material_colorC

Set material base color.

Inputs: name (required), color (required). Returns: object

set_material_nodesC

Apply structured node operations to a material.

Inputs: name (required), operations (required). Returns: object

set_material_propertiesC

Set common Principled BSDF properties.

Inputs: name (required), properties (required). Returns: object

set_object_originC

Set object origin.

Inputs: name (required), origin_type. Returns: object

set_object_parentD

Parent an object.

Inputs: name (required), parent (required), keep_transform. Returns: object

set_object_shadingC

Set smooth or flat shading.

Inputs: name (required), smooth. Returns: object

set_object_transformC

Set full object transform.

Inputs: name (required), scale, location, rotation. Returns: object

set_object_visibilityC

Set object visibility flags.

Inputs: name (required), hide_render, hide_select, hide_viewport. Returns: object

set_output_pathC

Set render output path.

Inputs: path (required). Returns: object

set_render_settingsC

Update render settings with configured limits enforced.

Inputs: settings (required). Returns: object

smooth_meshC

Smooth mesh vertices.

Inputs: name (required), factor, repeat. Returns: object

subdivide_meshC

Subdivide mesh faces.

Inputs: name (required), cuts. Returns: object

triangulate_meshD

Triangulate a mesh.

Inputs: name (required). Returns: object

unparent_objectC

Unparent an object.

Inputs: name (required), keep_transform. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.2/5.0

    Scored across 156 tools

    Disambiguation2/5

    Many tools overlap heavily: get_materials vs list_materials, get_modifiers vs list_modifiers, get_scene_info vs get_scene_summary, and create_primitive vs dozens of primitive-specific creators. Render/capture tools also blur together (render_scene, render_preview, render_final; capture_viewport, get_viewport_screenshot, capture_scene_preview). An agent can still pick a reasonable tool in many cases, but several boundaries are genuinely unclear.

    Naming Consistency3/5

    The surface is overwhelmingly snake_case, but verb conventions are inconsistent: get_ and list_ are used interchangeably for the same resource (materials/modifiers), some tools are noun-only (camera_view, mesh_cleanup, organize_scene), and capture_ vs render_ vs get_ overlap conceptually. It remains readable, but the naming does not reliably encode resource+action.

    Tool Count1/5

    156 tools is far beyond a well-scoped surface, even for a broad Blender domain. The set contains many convenience wrappers and near-duplicates (create_sphere, create_uv_sphere, create_primitive, create_cube, etc.) that inflate the count without adding distinct capability.

    Completeness5/5

    Coverage is extremely broad: scene/object inspection, mesh editing, materials and nodes, cameras, lights, rendering, animation, assets, file operations, collections, viewport capture, and Python execution. Almost every core Blender workflow appears represented, with no obvious lifecycle dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-capable AI clients to control a local Blender workstation through a secure HTTP gateway for 3D scene inspection, modeling, rigging, animation, materials, rendering, import/export, and controlled Python automation. Supports permission profiles and authentication modes to keep Blender execution local while allowing AI-assisted production workflows.
      1
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI clients to discover, inspect, and run 2,000+ AI models and data APIs—including LLMs, image, video, and audio generation—through a single authenticated local bridge with per-call pricing shown before execution. It also supports run status tracking, account balance checks, and rollback from one browser sign-in.
      556,724 npm
      MIT