# ahujasid/blender-mcp [Health: Active] **Category:** 📐 Architecture & Design **Repository:** https://github.com/ahujasid/blender-mcp **GitHub Stars:** 32489 **Views:** 11 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/ahujasid-blender-mcp ## Description Open-source MCP to use Blender with any LLM ## Tools Capabilities this server exposes over MCP: - **get_addon_status** — Check whether the connected Blender addon matches this MCP server version. If outdated, tells the user how to update via `uvx mcp-for-blender install-addon` (then restart or re-enable the addon in Blender). `telemetry_consent` reports whether data collection is on, off, or null if Blender could not be reached. Use it to answer telemetry status questions. - **disable_telemetry** — Turn OFF collection of prompts, code, screenshots and scene data. Use this whenever the user asks to stop data collection, opt out of telemetry, or stop sharing their data. Takes effect immediately. This tool can only turn collection OFF. Turning it back on is done by the user in Blender under Preferences > Add-ons > Blender MCP. - **get_scene_info** — Get detailed information about the current Blender scene Parameters: - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. Required. - **get_object_info** — Get detailed information about a specific object in the Blender scene. Parameters: - object_name: The name of the object to get information about - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. - **get_viewport_screenshot** — Capture a screenshot of the current Blender 3D viewport. Parameters: - max_size: Maximum size in pixels for the largest dimension (default: 800) - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. Returns the screenshot as an Image. - **execute_blender_code** — Execute arbitrary Python code in Blender. Make sure to do it step-by-step by breaking it into smaller chunks. Parameters: - code: The Python code to execute - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. - **describe_node_type** — Look up the property and socket schema of a Blender node type, without touching the current scene. Answers exactly the questions that otherwise take several trial-and-error execute_blender_code calls: what are this node's inputs/outputs (name, type, socket index, default value), what non-default properties does it have (e.g. data_type, blend_type, sky_type), and what enum values are valid for each. Internally this creates a throwaway node in a scratch node tree, optionally applies property_overrides, reads its schema, then deletes the scratch tree - it never modifies anything the user can see. Use this BEFORE writing code that indexes a node's sockets or sets an enum property, instead of guessing socket order or enum spelling. Parameters: - bl_idname: The node's bl_idname, e.g. "ShaderNodeMix", "ShaderNodeTexSky", "ShaderNodeBsdfPrincipled". - property_overrides: Optional dict of property values to set on the node before reading its sockets, e.g. {"data_type": "RGBA"} for a Mix node. Socket layout for many nodes depends on these mode-like properties, so set them here to see the real layout for the mode you intend to use. - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. - **bpy_api_lookup** — Structured Blender RNA/API reference lookup: types, properties, functions, and operators. Returns real signature data as JSON - argument names, types, whether each is required, enum identifiers, min/max, defaults - instead of text that has to be scraped out of help() output. Use this instead of guessing an operator's argument names or a property's valid enum values. Query forms: - "ShaderNodeTexSky" -> full type schema: all properties + methods - "ShaderNodeTexSky.sky_type" -> one property's type, enum items, default - "Object.ray_cast" -> one method's parameters and return values - "bpy.ops.mesh.primitive_cube_add" -> operator parameters (name, type, default, enum items) A leading "bpy." / "bpy.types." is optional and stripped automatically. If a name is not found, the result includes a "did_you_mean" list of close matches. Parameters: - query: The type, property, method, or operator path to look up (see forms above). - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. - **get_polyhaven_categories** — Get the categories and attributes you can filter Poly Haven assets by. Every asset sits in exactly one category, given as a path like "Coast & Water/Beaches/Sandy Beaches". Filtering is inclusive, so passing a parent path to search_polyhaven_assets also returns everything beneath it. Categories describe what an asset IS. Qualities like weather, condition or material are separate attributes, and every attribute this type supports is listed in the response with the exact values it accepts. Pass those to search_polyhaven_assets's `attributes`. Parameters: - asset_type: hdris, textures, models, or all. Asking for one type returns its full tree; "all" returns only the top two levels of each. - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. - **search_polyhaven_assets** — Search Poly Haven's library of free CC0 HDRIs, textures and models. Parameters: - query: What you are looking for, in plain words ("rusty metal", "overcast afternoon", "wooden chair"). Poly Haven's search understands intent and synonyms in any language, so describe the thing rather than guessing at keywords - "couch" finds sofas. Leave it out to browse the most downloaded assets instead. - asset_type: hdris, textures, models, or all - category: Optional single category path, exactly as get_polyhaven_categories returns it ("Metal/Sheet & Corrugated"). Matching is inclusive, so a parent path also returns everything nested beneath it. - attributes: Optional filters on an asset's qualities, as key/value pairs - {"weather": "clear"}, {"material": ["wood", "metal"]} to match either, {"rigged": true}. Call get_polyhaven_categories for the keys and values each asset type accepts; an unrecognised one is an error, not an empty result. - min_size_m: Optional floor on an asset's real-world size, in metres. A texture covers a fixed real-world area, so a 0.5m one tiled across a 4m wall repeats eight times and reads as an obvious pattern rather than as a wall. Filter on it when the surface is large: min_size_m=2 for walls, floors and ground, and leave it out for props. Only textures and models publish a size, so HDRIs are excluded by this filter. - limit: How many results to return (default 20, maximum 50) - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. Results are returned in ranked order, most relevant first. The library always returns its closest matches even for a query it has nothing for, so judge the results themselves rather than assuming the top one is right. Two things worth reading in the results before picking one. The real-world size decides how many times a texture repeats across a surface, and its `surface_use` attribute says what it was photographed for - a texture tagged `object` is a prop material, not a wall. get_polyhaven_asset_preview shows the thumbnail for a few hundred kilobytes, which is cheaper than importing the wrong one. Returns each asset's id, name, type, author, category, tags and page URL. - **get_polyhaven_asset_preview** — Get a preview thumbnail of a Poly Haven asset by its ID. Use this to check an asset looks right before downloading it. A thumbnail is a few hundred kilobytes against a 4k texture's 24MB, so looking first is much cheaper than importing the wrong thing and trying again. Parameters: - asset_id: The Poly Haven asset ID (obtained from search_polyhaven_assets) - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. Returns the asset's thumbnail as an Image. - **download_polyhaven_asset** — Download and import a Polyhaven asset into Blender. Parameters: - asset_id: The ID of the asset to download - asset_type: The type of asset (hdris, textures, models) - resolution: The resolution to download. Poly Haven offers 1k, 2k, 4k and 8k for most assets, and up to 16k or 24k for some HDRIs. File size grows roughly fourfold per step, so prefer 1k-2k for background or filler assets and 4k for anything held close to camera. If a resolution is unavailable, the error names the ones that are. - file_format: Optional. hdr (default) or exr for HDRIs; jpg (default), png or exr for textures. Models are always imported from .blend and take no format argument: Poly Haven authors them in Blender and generates every other format from that file, so glTF and FBX are lossy renderings of a material that ships with the asset. - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. Returns a message indicating success or failure. - **set_texture** — Apply a previously downloaded Polyhaven texture to an object. Replaces every existing material slot on the object, which cannot be undone. Parameters: - object_name: Name of the object to apply the texture to - texture_id: ID of the Polyhaven texture to apply (must be downloaded first) - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. Returns a message indicating success or failure. - **get_polyhaven_status** — Check if PolyHaven integration is enabled in Blender. Returns a message indicating whether PolyHaven features are available. - **get_hyper3d_status** — Check if Hyper3D Rodin integration is enabled in Blender. Returns a message indicating whether Hyper3D Rodin features are available. - **get_sketchfab_status** — Check if Sketchfab integration is enabled in Blender. Returns a message indicating whether Sketchfab features are available. - **search_sketchfab_models** — Search for models on Sketchfab with optional filtering. Parameters: - query: Text to search for - categories: Optional comma-separated list of categories - count: Maximum number of results to return (default 20) - downloadable: Whether to include only downloadable models (default True) - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. Returns a formatted list of matching models. - **get_sketchfab_model_preview** — Get a preview thumbnail of a Sketchfab model by its UID. Use this to visually confirm a model before downloading. Parameters: - uid: The unique identifier of the Sketchfab model (obtained from search_sketchfab_models) - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. Returns the model's thumbnail as an Image for visual confirmation. - **download_sketchfab_model** — Download and import a Sketchfab model by its UID. The model will be scaled so its largest dimension equals target_size. Parameters: - uid: The unique identifier of the Sketchfab model - target_size: REQUIRED. The target size in Blender units/meters for the largest dimension. You must specify the desired size for the model. Examples: - Chair: target_size=1.0 (1 meter tall) - Table: target_size=0.75 (75cm tall) - Car: target_size=4.5 (4.5 meters long) - Person: target_size=1.7 (1.7 meters tall) - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. - Small object (cup, phone): target_size=0.1 to 0.3 Returns a message with import details including object names, dimensions, and bounding box. The model must be downloadable and you must have proper access rights. - **get_polypizza_status** — Check if Poly Pizza integration is enabled in Blender. Returns a message indicating whether Poly Pizza features are available. - **search_polypizza_models** — Search for models on Poly Pizza with optional filtering. Parameters: - query: Text to search for. May be left empty if at least one filter is given. - category: Optional category name, e.g. "Animals", "Furniture & Decor", "Transport", "Nature", "Buildings", "People & Characters", "Food & Drink", "Weapons", "Clutter", "Objects", "Scenes & Levels", "Other" - licence: Optional licence filter, either "CC0" (no credit required) or "CC-BY" (credit required) - animated: When True, return only animated models (default False) - limit: Maximum number of results to return (default 20, the API caps it at 32) - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. Returns a formatted list of matching models, with licence and triangle count on every row so a low-poly, permissively licensed asset can be picked without a second call. - **download_polypizza_model** — Download and import a Poly Pizza model by its ID. Poly Pizza models come from the rescued Google Poly archive, so their scale and origins are arbitrary. Pass normalize_size=True with a real-world target_size unless you have a reason not to. Parameters: - model_id: The Poly Pizza model ID (obtained from search_polypizza_models) - normalize_size: If True, scale the model so its largest dimension equals target_size - target_size: The target size in Blender units/meters for the largest dimension. Examples: - Chair: target_size=1.0 (1 meter tall) - Table: target_size=0.75 (75cm tall) - Car: target_size=4.5 (4.5 meters long) - Person: target_size=1.7 (1.7 meters tall) - Small object (cup, phone): target_size=0.1 to 0.3 - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. Returns a message with import details including object names, dimensions, bounding box, and the attribution string, which is also written onto each imported root object as the custom properties polypizza_attribution, polypizza_id and polypizza_licence. - **generate_hyper3d_model_via_text** — Generate 3D asset using Hyper3D by giving description of the desired asset, and import the asset into Blender. The 3D asset has built-in materials. The generated model has a normalized size, so re-scaling after generation can be useful. Parameters: - text_prompt: A short description of the desired model in **English**. - bbox_condition: Optional. If given, it has to be a list of floats of length 3. Controls the ratio between [Length, Width, Height] of the model. - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. Returns a message indicating success or failure. - **generate_hyper3d_model_via_images** — Generate 3D asset using Hyper3D by giving images of the wanted asset, and import the generated asset into Blender. The 3D asset has built-in materials. The generated model has a normalized size, so re-scaling after generation can be useful. Parameters: - input_image_paths: The **absolute** paths of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in MAIN_SITE mode. - input_image_urls: The URLs of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in FAL_AI mode. - bbox_condition: Optional. If given, it has to be a list of ints of length 3. Controls the ratio between [Length, Width, Height] of the model. - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. Only one of {input_image_paths, input_image_urls} should be given at a time, depending on the Hyper3D Rodin's current mode. Returns a message indicating success or failure. - **poll_rodin_job_status** — Check if the Hyper3D Rodin generation task is completed. For Hyper3D Rodin mode MAIN_SITE: Parameters: - subscription_key: The subscription_key given in the generate model step. Returns a list of status. The task is done if all status are "Done". If "Failed" showed up, the generating process failed. This is a polling API, so only proceed if the status are finally determined ("Done" or "Canceled"). For Hyper3D Rodin mode FAL_AI: Parameters: - request_id: The request_id given in the generate model step. Returns the generation task status. The task is done if status is "COMPLETED". The task is in progress if status is "IN_PROGRESS". If status other than "COMPLETED", "IN_PROGRESS", "IN_QUEUE" showed up, the generating process might be failed. This is a polling API, so only proceed if the status are finally determined ("COMPLETED" or some failed state). - **import_generated_asset** — Import the asset generated by Hyper3D Rodin after the generation task is completed. Parameters: - name: The name of the object in scene - task_uuid: For Hyper3D Rodin mode MAIN_SITE: The task_uuid given in the generate model step. - request_id: For Hyper3D Rodin mode FAL_AI: The request_id given in the generate model step. Only give one of {task_uuid, request_id} based on the Hyper3D Rodin Mode! Return if the asset has been imported successfully. - **get_hunyuan3d_status** — Check if Hunyuan3D integration is enabled in Blender. Returns a message indicating whether Hunyuan3D features are available. - **generate_hunyuan3d_model** — Generate 3D asset using Hunyuan3D by providing either text description, image reference, or both for the desired asset, and import the asset into Blender. The 3D asset has built-in materials. Parameters: - text_prompt: (Optional) A short description of the desired model in English/Chinese. - input_image_url: (Optional) The local or remote url of the input image. Accepts None if only using text prompt. - user_prompt: The user's own words describing what they want, quoted verbatim (do not paraphrase or summarise). Pass the same goal on every call in a multi-step task so each action is linked to the intent behind it. Never substitute your own sub-goal, plan step, or status text; if the user has given no new instruction, repeat their previous words unchanged. Returns: - When successful, returns a JSON with job_id (format: "job_xxx") indicating the task is in progress - When the job completes, the status will change to "DONE" indicating the model has been imported - Returns error message if the operation fails - **poll_hunyuan_job_status** — Check if the Hunyuan3D generation task is completed. For Hunyuan3D: Parameters: - job_id: The job_id given in the generate model step. Returns the generation task status. The task is done if status is "DONE". The task is in progress if status is "RUN". If status is "DONE", returns ResultFile3Ds with one or more downloadable model URLs. Prefer a .glb URL when present (self-contained with materials); otherwise use a .zip/.obj asset URL. This is a polling API, so only proceed if the status are finally determined ("DONE" or some failed state). - **import_generated_asset_hunyuan** — Import the asset generated by Hunyuan3D after the generation task is completed. Parameters: - name: The name of the object in scene - zip_file_url: A model URL from ResultFile3Ds. Prefer a .glb URL when available; .zip/.obj URLs still work as a fallback. Return if the asset has been imported successfully. - **export_scene** — Export the whole scene, the current selection, or named objects to a GLB or FBX file on disk, so another application (a game engine, a viewer, a converter) can pick it up. Parameters: - filepath: Absolute path of the file to write (.glb or .fbx). Parent folders are created. - format: "glb" (default; keeps PBR materials, emission, skins, shape keys, animation) or "fbx". - object_names: Export only these objects (children included). Omit for selection_only or the whole scene. - selection_only: Export what is currently selected in Blender (ignored when object_names is given). - apply_modifiers: Bake modifiers on export. Use false for rigged / shape-key meshes. - user_prompt: The user's own words describing what they want, quoted verbatim. Returns JSON with path, bytes, selection_only and the exported object names. - **record_trajectory_feedback** — Record evaluation feedback for a captured trajectory step. Parameters: - feedback: One of accept | reject | undo | correction - correction_text: Optional free-text correction or follow-up (especially for correction) - step_index: Optional 0-based step index; defaults to the last recorded step - user_prompt: Optional goal/prompt context for the feedback row ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `uvx` (confidence: high): ```json "mcpServers": { "blender-mcp": { "command": "uvx", "args": ["blender-mcp"] } } ``` ## Documentation ## What ahujasid/blender-mcp does ahujasid/blender-mcp exposes Blender operations through MCP so an AI client can work with an open Blender session. The Blender side is an addon that starts a socket server; the Python MCP server receives tool calls and forwards commands to that addon. Core workflows include reading scene and object details, running arbitrary Blender Python, inspecting the 3D viewport, and checking Blender's RNA/API structures. Agents can also create, modify, and delete objects, control materials and colors through executed Blender code, and use screenshots or rendered views for visual verification. The server extends Blender with optional asset services. It can search, preview, download, and import Poly Haven assets; search and import downloadable Sketchfab models; search and import Poly Pizza models; and generate assets through Hyper3D Rodin or Hunyuan3D. Status tools report whether Poly Haven, Sketchfab, Poly Pizza, Hyper3D Rodin, or Hunyuan3D features are available. ## How it works The system has two components: the MCP server and the Blender addon. The addon must be installed and enabled in Blender, and it starts its server when Blender opens. In the Blender interface, the MCP for Blender panel can be used to start the server if it is not already running. Most tools accept the user's original prompt so a sequence of operations can remain linked to the same goal. Blender code is sent to the running application for execution. Asset generation services may use asynchronous jobs: the agent starts generation, polls for completion, and then imports the resulting asset. Asset tools include safeguards and selection steps. Poly Haven searches return categories, attributes, sizes, and ranked results; previews can be retrieved before downloading. Sketchfab models can also be previewed before import. Imported Sketchfab and Poly Pizza models can be normalized to a requested largest dimension, while generated assets may need additional rescaling. ## Setup and configuration Automatic setup is available through the installer scripts for macOS, Linux, and Windows, or through `uvx mcp-for-blender setup` when `uv` is already installed. The setup process can configure supported MCP clients, install the Blender addon, and enable it. New installations should use the `mcp-for-blender` package name; the older `blender-mcp` invocation remains compatible with existing setups. Manual setup requires Blender 3.0 or newer, Python 3.10 or newer, and the `uv` package manager. Add the server to the MCP client with `uvx mcp-for-blender`, then install the addon with `uvx mcp-for-blender install-addon`. In Blender, enable **Interface: MCP for Blender** under **Edit → Preferences → Add-ons**. Fully restart the AI client after configuration, then open Blender and confirm that the MCP server is running. Only one MCP server instance should be running for the connection, rather than starting separate instances for multiple clients. ## Tools and capabilities - Inspect the current scene or a named object. - Execute arbitrary Python code inside Blender. - Capture a 3D viewport screenshot with a configurable maximum dimension. - Query Blender RNA types, properties, methods, operators, signatures, enums, defaults, and suggested matches. - Inspect the sockets and properties of a Blender node type without changing the visible scene. - Check addon version compatibility and control telemetry opt-out. - Search, preview, download, and import Poly Haven HDRIs, textures, and models. - Apply a downloaded Poly Haven texture to an object. - Search, preview, and import downloadable Sketchfab models with a target size. - Search and import Poly Pizza models with optional licence, category, animation, and size controls. - Generate and import models through Hyper3D Rodin or Hunyuan3D, including polling tools for asynchronous jobs. ## Limitations and notes The Blender addon is required for scene operations, and integrations such as Poly Haven, Sketchfab, Hyper3D Rodin, and Hunyuan3D depend on their corresponding features being enabled in Blender. Sketchfab imports require the model to be downloadable and accessible to the user. Hyper3D image generation requires either absolute local image paths or image URLs according to the active Rodin mode. `execute_blender_code` runs arbitrary Python in Blender, so generated code should be reviewed when the task is sensitive. The `set_texture` operation replaces every existing material slot on its target object and cannot be undone. Poly Pizza assets can have arbitrary source scale and origins; normalization with a real-world target size is available for imports. Telemetry can be disabled immediately with `disable_telemetry`. That tool only turns collection off; re-enabling it is done by the user in Blender under **Preferences → Add-ons → Blender MCP**. The addon can collect prompts, code, screenshots, and scene data when telemetry is enabled. _Full upstream README: https://allmcps.com/mcp/ahujasid-blender-mcp/readme_