Step-by-Step Guide to Setting Up Blender MCP for Claude AI Integration

This guide will walk you through the process of setting up Blender MCP to integrate Blender with Claude AI. This integration allows you to control Blender using natural language prompts through Claude .  

Prerequisites

Before you begin, ensure you have the following software installed on your system:

1. Blender 3.0 or newer: Download the latest version from blender.org .  
2. Python 3.10 or newer: Download the latest version from python.org .  
3. Node.js (npm): Download the recommended version from nodejs.org .  
4. Homebrew (for macOS): Install it from brew.sh .  
5. PowerShell (for Windows): This is usually pre-installed on Windows .  
6. uv Package Manager: This is crucial for running the Blender MCP server .
   • macOS: Open Terminal and run brew install uv .  
   • Windows: Open PowerShell and run powershell -c "irm https://astral.sh/uv/install.ps1 | iex " . Then, set the Path environment variable to include C:\Users\<YourUsername>\.local\bin (replace <YourUsername> with your actual username) . Refer to the official uv website (docs.astral.sh/uv) for more detailed instructions .  
7. Claude for Desktop Application: Download and install the application from the official Claude website (claude.ai/download or support.anthropic.com) . The browser version is not supported .  

Installation and Setup

Follow these steps to install and set up the Blender MCP integration:

1. Install the Blender Add-on

1. Navigate to the BlenderMCP GitHub repository (likely github.com/ahujasid/blender-mcp) .  
2. Download the repository as a ZIP file or just the addon.py file . Ensure you have the latest version (e.g., 1.1.0 for Poly Haven and Hyper3D Rodin support) .  
3. Open Blender.
4. Go to Edit > Preferences .  
5. In the Preferences window, go to the Add-ons tab .  
6. Click on the Install... button (usually at the top right) .  
7. Browse to the location of the downloaded ZIP file or addon.py file, select it, and click “Install Add-on” .  
8. Enable the add-on by checking the box next to Interface: Blender MCP .  

2. Configure Claude for Desktop Integration

1. Open the Claude for Desktop application .
2. Go to Settings (usually a gear icon) .  
3. Navigate to the Developer tab .  
4. Click on Edit Config. If claude_desktop_config.json doesn’t exist, Claude will prompt you to create it . The file is typically located at ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows .  
5. Open the claude_desktop_config.json file with a text editor .  
6. Add the following JSON configuration within the mcpServers section :  

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": [
        "blender-mcp"
      ]
    }
  }
}

For Windows, you might need to use this configuration :  

{
  "mcpServers": {
    "blender": {
      "command": "cmd",
      "args": [
        "/c",
        "uvx",
        "blender-mcp"
      ]
    }
  }
}

1. Save the claude_desktop_config.json file .  
2. Completely quit the Claude application (e.g., Command+Q on Mac or by right-clicking the system tray icon on Windows and selecting “Quit”) [1, 9, 1].
3. Reopen the Claude application .  

3. Start the Blender MCP Server and Connect to Claude

1. Open Blender (if it’s not already open) .  
2. In Blender, press the ‘N’ key to open the 3D View sidebar .  
3. You should see a tab labeled “BlenderMCP” . If not, ensure the add-on is enabled in Preferences.  
4. In the “BlenderMCP” tab, you’ll find a button labeled “Connect to Claude” or “Start Server” . Click this button to start the MCP server within Blender. The default port should work .  
5. In the Claude desktop application, a hammer icon should appear in the bottom right corner of the input box .  
6. Clicking the hammer icon should display Blender MCP tools like “create object primitive,” “delete,” “blender code,” “modify,” and “set material,” confirming the connection .  

Usage

1. Ensure the Blender MCP server is running in Blender before using Claude to control it .  
2. The recommended startup order is: Open Claude first, then Blender, and then start the MCP server in Blender .  
3. Interact with Blender through Claude by giving prompts such as “Create a 3D house,” “Add a floor and beautiful lighting,” “Create a sphere and place it above the cube,” or ask questions about the current Blender scene .  
4. Claude will generate Python code and send commands to Blender to perform the actions .  
5. Claude might ask for permission to run Python code; this is necessary for the integration .  
6. Initial results might be basic and can be further refined in Blender .  
7. You can use reference images to guide Claude in creating 3D scenes .  
8. Blender MCP supports object manipulation, material control, scene inspection, and execution of arbitrary Python code .  
9. Optionally, enable the “Poly Haven” checkbox in the BlenderMCP tab to allow Claude to use assets from the Poly Haven API .  
10. Support for prompting 3D models using Hyper3D Rodin is also available . Note the free trial limitations .  

Troubleshooting

• Connection Issues: Ensure the Blender add-on server is running and the MCP server is correctly configured in Claude. Avoid running uvx blender-mcp directly in the terminal. Restarting both Claude and the Blender server can help .  
• Timeout Errors: Simplify your requests or break them into smaller steps .  
• Poly Haven Issues: Claude’s behavior with Poly Haven can sometimes be unpredictable .  
• For persistent issues, try restarting both Claude and Blender . Consult the BlenderMCP GitHub repository’s issues section for more help .  

Security Considerations

• The execute_blender_code tool allows Claude to run arbitrary Python code in Blender. Use this feature with caution and always save your work beforehand .  
• Using Poly Haven involves downloading assets. Disable it if you prefer not to download external files .  
• Break down complex operations into smaller steps .  

By following these steps, you should be able to successfully set up and use the Blender MCP integration with Claude AI. Remember to save your Blender work frequently.