BlendRelay MCP

A Blender AI add-on and Blender MCP server for creating and editing 3D scenes with natural-language prompts.

BlendRelay MCP brings AI 3D modeling and text-to-Blender workflows into Blender 4.5+. Connect Codex, Claude, Antigravity, or another MCP-compatible AI agent; describe what you want; attach design references; sketch over the viewport; or target selected objects and mesh elements. The agent can then inspect and update the open .blend scene through typed Blender tools.

Install from PyPI · View the source on GitHub

What you can do

• Generate complete scenes, environments, props, buildings, products, and abstract artwork.
• Edit selected objects with natural-language instructions.
• Work with selected vertices, edges, and faces in Blender Edit Mode.
• Use one or more reference images for shape, composition, material, or style guidance.
• Draw viewport sketches and adjustable target boxes to show where changes should happen.
• Create materials, lighting, cameras, modifiers, Geometry Nodes, animation, and renders.
• Save and restore automatic scene checkpoints if a result needs to be undone.

Before you install

You need:

• Blender 4.5 or newer. Open Blender once before running setup.
• uvx or Python 3.11+ with pip.
• One supported AI command-line agent, installed and signed in:
  • OpenAI Codex CLI
  • Google Antigravity CLI

Install BlendRelay

Open PowerShell or a terminal and run:

uvx blendrelay-mcp setup

Alternatively, install it with pip:

python -m pip install blendrelay-mcp
blendrelay-mcp setup

Setup creates the local runtime folders and installs the bundled Blender extension into the newest compatible Blender installation it finds.

To target a particular Blender version:

uvx blendrelay-mcp setup --blender-version 4.5

Enable it in Blender

1. Restart Blender after installation.
2. Open Edit → Preferences → Add-ons / Get Extensions.
3. Search for BlendRelay MCP and enable it.
4. Return to the 3D Viewport and press N to open the sidebar.
5. Select the BlendRelay tab.
6. Click Connect.

The floating HUD can be shown or hidden from the panel. Its prompt supports multiple lines: use Shift+Enter for a new line and Enter to run.

Connect your AI agent

Codex CLI

Register BlendRelay once with Codex:

codex mcp add blendrelay -- uvx blendrelay-mcp mcp
codex mcp list

Make sure blendrelay appears as enabled. In Blender, choose Codex, select a model available to your signed-in account, and click Connect.

Antigravity CLI

Install and sign in to Antigravity, then select Antigravity in the Blender panel. BlendRelay prepares the task-specific MCP configuration when it launches the agent. If your Antigravity permission policy blocks MCP tools, allow mcp(blendrelay/*) in the Antigravity settings.

Other MCP clients

Claude Desktop, Claude Code, Cursor, and other MCP clients can connect to Blender through the published package:

{
  "mcpServers": {
    "blendrelay": {
      "command": "uvx",
      "args": ["blendrelay-mcp", "mcp"]
    }
  }
}

This external-client connection does not require the Blender panel to launch Codex or Antigravity. Blender and the BlendRelay add-on still need to be open and connected.

Your first creation

In the Generate tab:

1. Choose the AI agent and model.
2. Choose a generation profile and quality level.
3. Leave the scope on Full Scene for a new scene.
4. Enter a clear prompt.
5. Click Generate or use the floating HUD.

Example prompt:

Create a polished studio product scene for a modern wireless speaker.
Use a dark graphite body, a woven fabric grille, soft bevels, and realistic PBR materials.
Place it on a simple pedestal with a large softbox key light, subtle rim lighting,
an 85 mm product camera, and a clean charcoal background. Keep all major parts
as separately named objects and frame the final camera for a 16:9 render.

Strong prompts usually include the subject, dimensions or scale, visual style, materials, lighting, camera composition, required separate parts, and the desired final output.

Edit existing work

For object-level edits:

1. Select one or more objects in Blender.
2. Enable Only selected objects.
3. Describe the requested change, including what must be preserved.

Only edit the selected chair. Make the backrest 15% taller, soften the outer edges,
replace the upholstery with dark green velvet, and preserve its location and dimensions.

For mesh edits, enter Blender Edit Mode, select the relevant vertices, edges, or faces, and enable Only selected geometry.

Only modify the selected faces. Inset them slightly, extrude inward by 3 cm,
and bevel the new boundary with three segments. Preserve the surrounding topology.

BlendRelay can capture focused views of the selection so the agent receives both scene data and visual context.

Use references, sketches, and target regions

• Add multiple images from Reference Images, or drag images onto the 3D Viewport.
• In Sketch & Region, draw strokes over the viewport to communicate paths, silhouettes, placement, or corrections.
• Use an adjustable target box when the requested creation or change belongs in a specific volume.
• State how each reference should be used. For example: “use image 1 for shape and image 2 only for materials.”

Reference images guide the agent; they are not automatically converted into exact production geometry. Include known dimensions whenever accuracy matters.

Choose a generation profile

Start with High quality for normal work. Use Maximum when visual finish matters more than generation time and token usage.

Checkpoints and safe iteration

BlendRelay saves a recovery checkpoint before an AI task and another after successful completion. Open Versions to save or restore scene states.

Save the main .blend file normally as well. The workspace identity is stored in the Blender file, allowing BlendRelay to reconnect the file to its existing references, logs, and checkpoints when you reopen it.

Update BlendRelay

For an uvx installation:

uvx --refresh blendrelay-mcp setup

For a pip installation:

python -m pip install --upgrade blendrelay-mcp
blendrelay-mcp setup

Restart Blender after updating so it loads the newly installed extension files.

Troubleshooting

Run the diagnostic command first:

uvx blendrelay-mcp doctor

If Blender shows Disconnected:

• Keep Blender open and click Connect again.
• Confirm the correct AI CLI is installed and signed in.
• For Codex, run codex mcp list and confirm the server is named blendrelay.
• Rerun uvx --refresh blendrelay-mcp setup after installing a new Blender version.
• Restart Blender after updating the add-on.

If an agent finishes without changing the scene, inspect the task log shown in the Blender panel. Common causes are a disconnected Blender bridge, an MCP permission denial, or an AI client registered under a different server name.

Local data

BlendRelay stores shared runtime data under %LOCALAPPDATA%\BlendRelayMCP on Windows. Each Blender scene receives its own folder under workspaces/<workspace-id>/ for references, agent logs, screenshots, sketches, and scene versions.

Set BLENDRELAY_DATA_DIR if you need a different storage location.

Advanced commands

• blendrelay-mcp doctor: Check the installation and runtime status.
• blendrelay-mcp install-addon: Reinstall the bundled Blender extension.
• blendrelay-mcp mcp: Start the MCP stdio gateway.
• blendrelay-mcp runtime serve: Start the local runtime bridge manually.

License

The Python MCP and runtime components are released under the MIT license. The Blender extension is released under GPL-3.0-or-later. See the license files in the repository for details.