Blender

You connect Blender with CSM.ai and language models through the Model Context Protocol (MCP) to enable AI-assisted editing and asset management inside Blender. This setup lets you search for assets, animate humanoids, and drive 3D modeling workflows with natural prompts from MCP clients like Cursor or Claude.

How to use

Launch the MCP server from the Blender project workspace and connect your MCP client (Cursor or Claude Desktop App) using the provided mcp configuration. When you send coordinated prompts, Blender executes actions such as creating or editing geometry, importing assets from CSM.ai, and applying textures or animations. Use natural language to choreograph scene changes, and let the MCP client orchestrate Blender actions through the server.

How to install

Prerequisites: ensure Python is installed and you can run Python from your system path.

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

cd blender-mcp

pip install -e .

Configuration and usage notes

Configure the MCP server in your client using the following stdio setup to run the Blender MCP server locally. This uses Python to launch the server module.

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

Blender configuration

1. Launch Blender
2. Open Edit → Preferences
3. Install the addon.py file from the repository
4. Ensure the Blender MCP addon appears in the 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 or Claude.

CSM.ai integration

For best results, enable vector search-based model retrieval. Create or select relevant modeling sessions on 3d.csm.ai to supply targeted assets for your project. The system can also access a broad collection of general 3D models when needed.

Quickstart / Try It Out

After entering your CSM API key in the Blender addon settings and confirming the MCP server is running (Cursor → MCP settings), open a chat in your MCP client and try a test 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.

Python Test Client

The repository includes a standalone Python client that demonstrates how to connect to the Blender MCP server programmatically. This is useful for testing and for building your own MCP clients.

python chat_client.py

Notes on alternate MCP clients

You can use other MCP clients like the Claude Desktop App. Use the same mcp.json configuration in the client UI to connect to the Blender MCP server.

Troubleshooting and tips

If you encounter issues, ensure you are in the blender-mcp directory when launching Cursor and that you are using the appropriate Python version (for example python3.10 if needed). If Blender is not available via your package manager on Linux, install it with your distribution’s package manager.

Available tools

session_search

Search public or private CSM.ai sessions to retrieve assets or guidance for MCP-based development.

mcp_animation

Animate humanoid meshes by triggering a Mixamo-based animation workflow through MCP prompts.

asset_generator

Use CSM.ai as an asset generator and manager to populate scenes with appropriate 3D models.