Installation¶

By default everything runs locally: a .NET tool started by your MCP client, and an extension inside Blender that listens on the loopback interface only, so nothing leaves the machine. A Blender on another machine is reached through an SSH tunnel instead; Blender on another machine covers installing the add-on there. A server can also run beside Blender in Docker and be reached over HTTPS; Blender in Docker sets that up.

What you need¶

macOS, Windows and Linux are all supported.

Step 1 — install the server¶

As a global tool (recommended)¶

dotnet tool install -g Snail.MCP.Blender

This gives you a s3l-mcp-blender command. If the shell answers command not found, add the tools folder to PATH: ~/.dotnet/tools on macOS and Linux, %USERPROFILE%\.dotnet\tools on Windows. GUI clients do not always inherit the shell PATH; when one cannot start the server, put the absolute path in command.

Without installing¶

dnx Snail.MCP.Blender --yes

In a client configuration that becomes "command": "dnx", "args": ["Snail.MCP.Blender", "--yes"].

From source¶

git clone https://github.com/orldev/Snail.MCP.Blender.git
cd Snail.MCP.Blender
dotnet build -c Release

The command is then dotnet with "args": ["<repo>/src/bin/Release/net10.0/Snail.MCP.Blender.dll"]. The repository's .mcp.json holds an entry for a Debug build, commented out; uncomment it to register that build with Claude Code.

Step 2 — register the server with your client¶

Claude Code¶

claude mcp add blender -- s3l-mcp-blender

Claude Desktop¶

In claude_desktop_config.json:

{
  "mcpServers": {
    "blender": { "command": "s3l-mcp-blender" }
  }
}

A server in Docker¶

A server that runs beside Blender in Docker is reached over HTTP instead of started by the client. For Claude Code:

claude mcp add --transport http --scope user blender https://blender.example.com/mcp \
  --header "Authorization: Bearer $(cat ~/.s3l-mcp-blender/remote/docker.token)"

Nothing else is installed on the client, the add-on included; Blender in Docker sets up the machine.

Cursor, VS Code, Codex¶

The same command in the client's MCP settings; the key is mcpServers or servers depending on the client.

Step 3 — install the add-on in Blender¶

Ask the agent to call blender_install_addon, or run it yourself from the client's tool list. It writes snail_bridge-<version>.zip into the data directory (~/.s3l-mcp-blender/addon) and lists the steps:

1. In Blender open Edit → Preferences → Get Extensions.
2. Open the drop-down arrow in the top-right corner and choose Install from Disk.
3. Pick the zip. The extension is enabled and starts listening at once.
4. In the 3D viewport press N, open the Snail tab and check that it says listening on port 9876.

The add-on starts with Blender from then on. Its preferences (Edit → Preferences → Get Extensions → Snail Bridge) hold the port, the autostart switch and the token. Leave the token empty: the add-on generates one into ~/.s3l-mcp-blender/state/token, readable by you only, and the server reads it from there, so a single-user machine needs nothing typed on either side.

Step 4 — check¶

Ask the agent to run blender_diagnose. With Blender open it reports blender.reachable: true and the Blender version. Then try add a cube at 0, 0, 1 and make it red.

Updating¶

dotnet tool update -g Snail.MCP.Blender

After a server update run blender_install_addon again and reinstall the zip: the add-on and the server share one command catalog and must match. They check each other — blender_diagnose reports addOn.status: current when the installed add-on is the build the server ships, older with the list of missing commands when it is behind, differs when it is another build that is not behind, and unknown when Blender does not answer.

Uninstalling¶

dotnet tool uninstall -g Snail.MCP.Blender

Remove the extension in Blender's preferences and delete ~/.s3l-mcp-blender, and ~/.snail-mcp-blender too when it is there: a link the server left at the old name when it moved the folder.