Skip to main content

Blender-specific MCP setup

Before continuing, create an account and API key, then connect and verify StudioTwin Web MCP. Web MCP owns every StudioTwin cloud operation and can also operate standalone.

Agent Skill

Install the StudioTwin Agent Skill for this workflow:

npx skills add realtwin/studiotwin-mcp-skill

For setup options and supported workflows, see the StudioTwin MCP overview.

This page covers only the Blender-specific components:

  1. Blender 5.1 or newer.
  2. Official Blender MCP server, launched by the MCP client.
  3. Official Blender MCP addon, installed in Blender to expose the local bridge.
  4. StudioTwin Blender addon, which provides local importers for downloaded StudioTwin outputs.

The components cooperate in this order:

StudioTwin Web MCP -> agent downloads files -> official Blender MCP
-> StudioTwin Blender addon importers -> Blender scene

The StudioTwin Blender addon is not an MCP server. It has no cloud, networking, generation-job, or API-key responsibility and accepts supported local files only.

Install the official Blender MCP​

The official Blender MCP consists of an addon in Blender and an MCP server for your client. The current official release documented here is v1.0.3.

1. Install the official addon​

  1. Install and launch Blender 5.1 or newer.
  2. Download the official MCP addon v1.0.3.
  3. In Blender, open Preferences → Get Extensions → Install from Disk and select the downloaded package, then enable MCP.

The official Blender MCP installation page also documents drag-and-drop installation and update notifications through the Blender Lab repository.

2. Install the official MCP server​

If your MCP client supports .mcpb bundles, download the current official bundle from the Blender MCP releases page and follow that client's bundle-installation instructions. Bundle support and configuration are client-specific.

For a stdio client, install from the versioned source as follows.

Prerequisites:

Windows PowerShell:

cd C:\
git clone --branch v1.0.3 --depth 1 https://projects.blender.org/lab/blender_mcp.git

macOS:

cd /Users/YOUR_USERNAME
git clone --branch v1.0.3 --depth 1 https://projects.blender.org/lab/blender_mcp.git

Linux:

cd /home/YOUR_USERNAME
git clone --branch v1.0.3 --depth 1 https://projects.blender.org/lab/blender_mcp.git

Then add the server to your MCP client's stdio configuration. Replace the example username with your actual absolute path. Do not use $HOME or ~ in client JSON.

Windows:

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\blender_mcp\\mcp",
        "run",
        "blender-mcp"
      ]
    }
  }
}

macOS:

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/YOUR_USERNAME/blender_mcp/mcp",
        "run",
        "blender-mcp"
      ]
    }
  }
}

Linux:

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/YOUR_USERNAME/blender_mcp/mcp",
        "run",
        "blender-mcp"
      ]
    }
  }
}

On first launch, uv run installs the server's declared dependencies and runs blender-mcp from the cloned mcp directory. See the official stdio setup guide for the upstream configuration.

After adding or changing this MCP client configuration, reconnect your client or use its supported hot-load mechanism. If the new tools remain unavailable, restart or reconnect your MCP client or agent harness session, then resume the task or conversation.

3. Start the local bridge safely​

Security warning

The official Blender MCP executes LLM-generated Python code in Blender without guards that prevent data removal or exfiltration. Back up your files first and run it in a virtual machine or another non-sensitive environment. Keep the bridge bound to the loopback host (localhost/127.0.0.1) rather than exposing it to your network.

Only after applying those precautions:

  1. In Blender Preferences, enable Allow Online Access. The v1.0.3 bridge will not start while this setting is disabled.
  2. Open the MCP extension preferences.
  3. Keep the bridge host on loopback and use the same port in any configuration that requires it (the default is 9876).
  4. Enable Auto Start, or click Start MCP Bridge Server, and confirm the interface reports Server is running.

Confirm that the local Blender MCP bridge is reachable from the environment where your MCP client or agent harness runs, including when WSL, a container, a VM, a remote machine, or another network namespace separates it from Blender. Remember that localhost refers to the client or harness environment and may not reach Blender across such a boundary. Keep the bridge loopback-only; resolve the boundary without exposing the bridge to a network.

Install the StudioTwin Blender addon​

  1. Download the addon package from the StudioTwin Blender addon releases page.
  2. In Blender, open Preferences → Get Extensions → Install from Disk and select the downloaded package.
  3. Enable StudioTwin and grant its local-file permission if Blender asks.

See the StudioTwin Blender addon overview for its role and support matrix.

When your target is an already-open interactive Blender scene, do not launch or use a second Blender process—including a headless or background process—for setup or verification. Use Blender MCP to verify the intended scene directly and confirm that it reports bpy.app.background == False.

Before spending credits, verify that:

  1. StudioTwin Web MCP is connected and exposes the live generation, job, and asset tools as described in the canonical Web MCP guide.
  2. The official Blender MCP reports Server is running.
  3. A read-only Blender MCP call reaches the intended open file and reports bpy.app.background == False.
  4. The enabled StudioTwin Blender addon exposes the importer needed for your supported local output.

The operating sequence is: generate and poll through StudioTwin Web MCP; have the agent resolve and download the completed output to a persistent local path; then use the official Blender MCP to call one matching local StudioTwin importer. Assignment or placement, saving, and rendering are separate stages.

Motion generation and download through Web MCP remain available. StudioTwin Blender motion import is Coming soon.