blendermcpiflow 1.0.0

Blender integration through the Model Context Protocol

BlenderMCP x CSM.ai x LLM Agents (e.g. Cursor / Claude)

Connect Blender, CSM.ai and LLMs via the Model Context Protocol (MCP). This integration enables text and image based editing capabilities in Blender.

      ╭───────────╮       ╭───────────╮       ╭───────────╮
      │  CSM.ai   │◄━━━━━►│  Blender  │◄━━━━━►│  MCP UI   │
      │ 3D Assets │       │    MCP    │       │e.g.Cursor │
      ╰─────┬─────╯       ╰─────┬─────╯       ╰─────┬─────╯
            │                   │                   │
            ▼                   ▼                   ▼
      ╭─────────────────────────────────────────────────╮
      │                                                 │
      │               BLENDER ENGINE                    │
      │        Creative 3D Modeling Environment         │
      │                                                 │
      ╰─────────────────────────────────────────────────╯

https://github.com/user-attachments/assets/496c2c69-4779-4569-9be0-80b767702c4c

Overview

BlenderMCP creates a bridge between Blender, CSM.ai and language models, allowing for powerful AI-assisted 3D modeling workflows.

MCP Feature List ✨

• 🔍 Ability to quickly search from public or private CSM.ai sessions. This allows interactive MCP based development. E.g. "Use CSM to get me a ghibli robot". Make sure you have some pre-generated robots on 3d.csm.ai or it will use some public session.

• 🏃 For any humanoid like mesh in the scene, ability to animate given a Mixamo file for maximum controllability. Here's an example (first name the mesh to animate, then the system will ask you for a local file path from Mixamo and instructions): MCP Animation Workflow

Installation

1. Clone the repository:

   git clone https://github.com/CommonSenseMachines/blender-mcp.git
   

2. Navigate to the project directory:

   cd blender-mcp
   

3. Install the package:

   pip install -e .
   

Troubleshooting

• Upgrade pip, e.g. python3 -m pip install --upgrade pip
• Use python3.10 -m pip install -e . if you don't normally use python

Cursor Configuration

1. Open Cursor in the root directory of the cloned blender-mcp repo.
2. Navigate to: Cursor → Settings → Cursor Settings → MCP → Add a new server
3. Add the following MCP configuration (see .mcp.json file):

{
    "mcpServers": {
        "blender": {
            "command": "python",
            "args": [
                "-m", "blender_mcp.server"
            ]
        }
    }
}

Troubleshooting

• Use Cursor from the blender-mcp directory
• Use python3.10 in mcp.json (or whatever your normal Blender Python version is)

Blender Configuration

1. Launch Blender
2. Navigate to Edit → Preferences
3. Install the addon.py file from this repository
4. Verify that the Blender MCP addon appears in your addon list
5. Start the MCP server and enable the 'Use CSM.ai 3D models' option
6. Enter your CSM API key to begin using the integration with Cursor

Troubleshooting

• In Ubuntu, you may have to sudo apt install blender.

CSM.ai Integration

For optimal performance, the MCP server utilizes vector search-based 3D model retrieval. To enhance your experience:

1. Visit 3d.csm.ai to create relevant modeling sessions
2. These sessions will provide targeted 3D assets for your specific projects
3. Alternatively, the system can access a large collection of general 3D models

This workflow creates a powerful ecosystem where:

• CSM.ai functions as your asset generator and manager
• Cursor serves as your AI coding assistant
• Blender operates as your execution environment

Quickstart / Try It Out

Once you have entered your CSM API key in the Blender addon settings and confirmed the MCP server is running (check Cursor Settings → MCP), you're ready to test the integration!

Simply open a new chat window in Cursor (with any project open) and paste the following prompt:

First, make sure to clear the scene. Then create a simple table just using blender, do no search for that. Once the table has been crafted, search for a chair on CSM AI, add it to the scene and place it next to the table. Then spell out the word "CSM x MCP" above the CSM asset, color it in #A157EE and make it very shiny metallic and rotate it 90deg so that it makes for a nice display facing the user. Also ensure that the table has nice textures.

This will trigger actions in Blender based on your instructions. The result from using the above prompt should look like this:

Instead of Cursor you can also use other MCP clients like the Claude Desktop App. See instructions in: Blender MCP. You will use the same mcp.json file as above but just enter it in the claude desktop UI.

Python Test Client

The repository includes a standalone Python client (chat_client.py) that demonstrates how to connect to the Blender MCP server programmatically. This is useful for:

• Testing the Blender MCP connection without using Cursor or Claude Desktop
• Understanding the MCP protocol and API
• Developing your own custom MCP clients
• Debugging MCP server responses

Running the Python Client

1. Start Blender and enable the MCP addon as described in the "Blender Configuration" section.

2. Open a terminal in the repository root and run:

   python chat_client.py
   

Client Features

The Python client connects to Blender via the Model Context Protocol and demonstrates several capabilities:

• Lists all available MCP tools organized by category (query, creation, modification, etc.)
• Retrieves and displays scene information from Blender
• Creates a simple cube in the scene
• Gets detailed information about the created object
• Checks CSM.ai integration status

Extending the Client

The client demonstrates how to work with the MCP format and handle various response types. You can use it as a starting point to:

• Create scripts that automate Blender tasks
• Build custom UIs on top of Blender's MCP capabilities
• Integrate Blender with your own applications

The code includes helper functions for extracting text from MCP responses and parsing JSON content, making it easy to work with the returned data.

Acknowledgements

Blender MCP