vipermesh-blender

<div align="center"> <!-- i18n:languages:start -->

English | Español | 简体中文 | Français | 日本語 | Deutsch | Português (Brasil)

<!-- i18n:languages:end -->

<a href="https://openrootdev.github.io/vipermesh-blender/"><img src="site/assets/brand-mark.png" alt="ViperMesh logo" width="104" height="104"></a>

<h1>ViperMesh for Blender</h1> <p>Open-source Blender MCP server and addon for AI agents.</p>

AI assistance for Blender, with less code and less waiting.

Designed for faster scene edits, fewer AI tokens and better-checked results.

<p> <a href="https://github.com/OpenRootdev/vipermesh-blender/releases/latest"><img src="site/assets/readme-download.svg" alt="Download Blender addon" width="240" height="44"></a> <a href="docs/client-setup.md"><img src="site/assets/readme-setup.svg" alt="Setup guide" width="160" height="44"></a> </p>

Project overview and setup | ViperMesh Studio waitlist

</div>

---

ViperMesh for Blender is a free, open-source Blender MCP server and addon that lets a compatible AI assistant work inside your Blender scene. It is for Blender artists, hobbyists and game creators who want help making and editing 3D scenes, not another coding project.

The goal: faster AI-assisted work, fewer AI tokens and better-checked results. Your assistant gets ready-to-use Blender actions instead of having to write new Python code for many common edits. You keep working in Blender and decide what you want the assistant to help with.

Watch The Overview

Watch the 77-second video or download the MP4. See how your AI client uses ready-made Blender actions, why less generated code can help, and how to get started. This is an illustrated overview with music, not a timed benchmark recording. GitHub's README links to the playable video.

Why ViperMesh for Blender?

| What matters to you | How ViperMesh helps | | --- | --- | | Less AI usage | Reusable actions reduce the Blender code the assistant needs to generate for covered tasks. | | Less waiting | The connection stays open, and related actions can run together instead of repeating setup for each step. | | Better-checked scenes | Built-in checks help identify floating objects, wrong orientations and clearance problems; the assistant can inspect images and repair mistakes. | | Easier for your assistant | Discoverable tools and concise guidance explain what actions are available and how to use them. | | Room for custom work | The assistant can still write Python when your request needs something the ready-made tools do not cover. |

AI tokens are the units of text a model reads and writes. Generating less code can reduce AI usage, but total tokens, cost and time also depend on your model and the task. Scene checks help with correctness; they do not guarantee a beautiful or error-free result.

One Reference, Two Blender Workflows

<p align="center"> <a href="site/assets/scandinavian-entryway-comparison.png"><img src="site/assets/scandinavian-entryway-comparison.png" alt="Historical scene comparison: reference image on the left, ViperMesh MCP Blender viewport in the centre, and original BlenderMCP viewport on the right" width="960"></a> </p>

One historical image-reconstruction test using the ViperMesh Blender MCP harness and available assets. Only the centre heading was relabelled; the reference and both scene screenshots are unchanged. This is one example, not a guarantee of every result. The public addon does not bundle private Studio asset libraries.

Read the Blender MCP case study, Part One | Open the full-size comparison | Image integrity record

What Can It Help With?

• Build, move, duplicate and arrange objects in a scene.
• Soften edges, adjust materials, set cameras and change lighting.
• Check whether objects sit on their supports or leave enough space.
• Assist with mesh cleanup, retopology, UV preparation, rigging and weights.
• Work with animation settings, prepare exports and inspect results.

For example, you could ask your assistant:

Move the basket under the right side of the table, without intersecting its legs.

Soften the sharp edges on this furniture, keeping its overall shape.

Check this scene for unsupported objects, then show me what needs fixing.

These are examples of requests, not prebuilt scene templates. You do not need to write Blender Python yourself for the operations the tools cover.

How Is It Different From The Original BlenderMCP?

ViperMesh builds on the original BlenderMCP project by Siddharth Ahuja, now named MCP for Blender. The main difference is its emphasis on a broad set of ready-made editing actions, reusable workflows and scene checks, rather than relying on newly generated Python for common edits.

Both projects can inspect scenes and run custom Python. The original project also offers asset and generation integrations. ViperMesh's aim is to make everyday scene operations more token-efficient, faster, simpler for assistants to use and easier to validate. This is not a claim that it wins every task or that the public connector includes every feature of ViperMesh Studio.

Website installation guide · Harness Library listing

Requirements

• Blender 5.2 for the currently tested release target
• Node.js 20 or newer
• An MCP-compatible client that supports stdio servers

MCP, short for Model Context Protocol, is a connection standard that lets an AI assistant use tools in another application. You need an AI app that supports these connections; installing the addon alone does not add an AI model to Blender.

Install

1. Install the Blender addon

Download the versioned addon .py or addon .zip from the latest release. In Blender:

1. Open Edit > Preferences > Add-ons.
2. Choose Install from Disk and select the downloaded Python file.
3. Enable ViperMesh for Blender.
4. Open the 3D Viewport sidebar, select ViperMesh, and click Start Local Bridge.

Keep the bridge running for the complete agent session.

2. Install the MCP server

Packaged option: Download the v1.3.0 MCPB bundle and import it into a client that supports local MCPB extensions. It contains the Node server and its dependencies, so you do not need to clone or build the repository. Node.js and the separately enabled Blender addon are still required.

The connector is also listed on Smithery and in the official MCP Registry. These listings distribute the local connector, not a hosted Blender service. See distribution and bundle setup for the checksum, manual extraction option, and current validation limits.

Source option: Until the npm package is published, clone and build it:

git clone https://github.com/OpenRootdev/vipermesh-blender.git
cd vipermesh-blender
npm install
npm run build

3. Connect your AI assistant

When using the MCPB import, the client reads its launch configuration from the bundle. For the source option, use the built entry point from an absolute path:

{
  "mcpServers": {
    "vipermesh-blender": {
      "command": "node",
      "args": [
        "C:/absolute/path/to/vipermesh-blender/dist/public-portable-blender-mcp.js"
      ]
    }
  }
}

Start this command once through the MCP client. Do not invoke npm, npx, or tsx again for each Blender operation. See MCP client setup for Codex, JSON-configured clients, compatibility, and the optional Docker MCP Toolkit route.

Technical Details

The sections below are for setting up or developing an AI connection. Blender users can start with the installation steps and the example requests above.

Connection Model

MCP-compatible AI assistant
        |
        | stdio, one long-lived process
        v
ViperMesh MCP server
        |
        | serialized loopback connection
        v
ViperMesh Blender addon (127.0.0.1:9876)
        |
        v
Blender scene

The MCP server opens no network listener. The Blender addon listens on loopback by default and reports Stopped, Ready, Agent connected, or Error in the ViperMesh sidebar.

First Agent Calls

1. Call bootstrap_vipermesh_session.
2. Inspect the scene with call_blender_tool(name="get_scene_info").
3. Search task guidance with search_3d_guidance.
4. Discover only the relevant capabilities with list_blender_tools.
5. Build, inspect and repair, then finalize and save.

The public MCP surface includes:

• bootstrap_vipermesh_session
• check_blender_connection
• list_blender_tools
• call_blender_tool
• call_blender_tool_batch
• run_blender_scene_stage
• get_blender_agent_context
• search_3d_guidance
• get_3d_guidance_document

Read the complete connector manual for request shapes, batching rules, staged workflows, local tool skills, and troubleshooting. The repository also ships an installable using-vipermesh-blender agent skill.

Security

This connector is intended for a trusted local workstation. execute_code can run arbitrary Python in Blender. Only connect trusted MCP clients, keep the bridge on loopback, and review high-impact or destructive operations.

See SECURITY.md for the trust boundary and private vulnerability reporting process.

Public Connector Scope

This repository contains the open-source Blender addon, portable MCP server, portable public tool skills, and connector tests. It does not include the ViperMesh application, authentication, billing, private prompts, private RAG data, cloud model routing, private assets, raw benchmark traces, or private evaluation datasets. The illustrated comparison is separately provided public evidence, not a bundled asset library.

The connector does not bundle a commercial 3D generation provider. Neural generation can be added later through provider-neutral authenticated services without embedding third-party credentials in Blender.

Frequently Asked Questions

Do I need a paid ViperMesh account?

No. The public addon and local connection are free to use without a ViperMesh account. Your AI app or model provider may charge separately. The addon does not include free AI model access.

Do I need to