ClaudeKit Blender MCP

Model Context Protocol server for Blender 3D integration with ClaudeKit enhancements.

Installation • Configuration • Tools • Troubleshooting

Features

• 🎨 26 Blender Tools: Complete control over Blender from Claude Desktop
• 🎭 Object Management: Create, modify, transform objects
• 🎬 Scene Control: Manage scenes, cameras, lighting
• 📦 Asset Integration: Import from Poly Haven, Sketchfab, and more
• 🖼️ Viewport Control: Take screenshots, render scenes
• 🔧 Material & Texture Management: Full material editing capabilities
• 📝 Python Scripting: Execute custom Blender scripts

Installation

Option 1: Global Installation (Production Use)

npm install -g claudekit-blender-mcp

Option 2: Local Development

# Clone the repository
git clone https://github.com/yourusername/claudekit-blender-mcp.git
cd claudekit-blender-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Step 1: Install Blender Addon

1. Open Blender
2. Go to Edit → Preferences → Add-ons
3. Click Install... button
4. Navigate to and select: blender-addon/addon.py
5. Enable the addon by checking the box next to "Blender MCP Server"

The addon will automatically start the WebSocket server when Blender launches.

Step 2: Configure Claude Desktop

The configuration file location varies by OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration for Global Installation

{
  "mcpServers": {
    "blender": {
      "command": "npx",
      "args": ["-y", "claudekit-blender-mcp"]
    }
  }
}

Configuration for Local Development

If using Node Version Manager (fnm, nvm, asdf):

{
  "mcpServers": {
    "blender": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/claudekit-blender-mcp/dist/index.js"]
    }
  }
}

Find your Node.js path:

# For fnm users
which node  # Then use realpath or readlink to get actual path

# For nvm users
nvm which current

# Example paths:
# fnm: /Users/username/.local/share/fnm/node-versions/v20.19.5/installation/bin/node
# nvm: /Users/username/.nvm/versions/node/v20.19.5/bin/node

If Node.js is in system PATH:

{
  "mcpServers": {
    "blender": {
      "command": "node",
      "args": ["/absolute/path/to/claudekit-blender-mcp/dist/index.js"]
    }
  }
}

Step 3: Restart Claude Desktop

Important: You must completely restart Claude Desktop (not just reload):

# macOS
killall "Claude" && sleep 2 && open -a "Claude"

# Windows
# Close Claude Desktop completely from system tray, then reopen

# Linux
killall claude && claude

Verification

Test the Connection

Open Claude Desktop and try these commands:

What MCP tools do you have available?
List all Blender tools
Create a cube in Blender

Expected Output

You should see 26 tools available:

Core Blender Tools (10):

• blender_execute_python: Execute Python code in Blender
• blender_create_object: Create objects (cube, sphere, etc.)
• blender_list_objects: List all objects in scene
• blender_modify_object: Modify object properties
• blender_delete_object: Delete objects
• blender_get_scene_info: Get scene information
• blender_render_scene: Render the current scene
• blender_save_file: Save .blend file
• blender_take_screenshot: Capture viewport
• blender_import_file: Import 3D files

Asset Integration Tools (16):

• polyhaven_search_assets: Search Poly Haven library
• polyhaven_get_asset_info: Get asset details
• polyhaven_download_asset: Download assets
• And more...

Troubleshooting

Error: spawn node ENOENT

Problem: Claude Desktop cannot find the node command.

Solution: Use absolute path to Node.js in your config.

# Find your Node.js path
which node
realpath $(which node)  # Get the actual path if using fnm/nvm

# Update config with absolute path
# Example:
{
  "mcpServers": {
    "blender": {
      "command": "/Users/username/.local/share/fnm/node-versions/v20.19.5/installation/bin/node",
      "args": ["/path/to/project/dist/index.js"]
    }
  }
}

Why this happens:

• Claude Desktop runs with its own PATH environment
• Node version managers (fnm, nvm, asdf) modify shell PATH
• Claude Desktop's PATH doesn't include these custom paths
• Solution: Use absolute path to bypass PATH lookup

MCP Server Not Connecting

1. Check Claude Desktop logs:

# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows
# Check: %APPDATA%\Claude\logs\

# Linux
tail -f ~/.config/Claude/logs/mcp*.log

2. Verify Blender addon is running:

• Open Blender → Window → Toggle System Console
• Look for: "BlenderMCP server started on localhost:9876"

3. Test MCP server manually:

# For local development
cd /path/to/claudekit-blender-mcp
node dist/index.js

# Should see:
# Starting ClaudeKit Blender MCP Server...
# Registered 10 core Blender tools
# Registered 16 asset integration tools

JSON Configuration Errors

Validate your config file:

# macOS/Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

# Should output formatted JSON without errors

Common mistakes:

• Missing commas between entries
• Trailing commas at end of objects/arrays
• Incorrect quote types (use " not ')
• Missing closing brackets

Blender Connection Timeout

Check Blender addon status:

1. Blender → Edit → Preferences → Add-ons
2. Search for "MCP"
3. Ensure checkbox is checked
4. Check console for errors

Firewall issues:

• Ensure localhost connections are allowed
• Default port: 9876
• Protocol: TCP Socket

Module Not Found Errors

For local development:

cd /path/to/claudekit-blender-mcp
npm install  # Reinstall dependencies
npm run build  # Rebuild

Check Node.js version:

node --version  # Should be >= 18.0.0

Development

Project Structure

claudekit-blender-mcp/
├── src/
│   ├── server.ts          # MCP server setup
│   ├── tools/             # Tool implementations
│   │   ├── objects.ts     # Object manipulation
│   │   ├── scene.ts       # Scene management
│   │   ├── materials.ts   # Material system
│   │   ├── assets.ts      # Asset integration
│   │   └── ...
│   └── utils/             # Utilities
├── dist/                  # Compiled JavaScript
├── blender-addon/
│   └── addon.py          # Blender addon
└── docs/                 # Documentation

Development Workflow

# Watch mode (auto-rebuild on changes)
npm run dev

# Build once
npm run build

# Clean build
npm run clean && npm run build

# After making changes:
# 1. Rebuild: npm run build
# 2. Restart Claude Desktop
# 3. Test changes

Running Tests

# Run all tests (coming soon)
npm test

# Test specific tool
npm test -- objects

Available Tools

Core Blender Operations

• Object Management: Create, modify, delete, transform objects
• Scene Control: Manage scenes, cameras, lighting
• Viewport: Take screenshots, change view angles
• Rendering: Render images and animations
• File I/O: Import/export various 3D formats

Asset Integration

• Poly Haven: Search and download HDRIs, textures, models
• Sketchfab: Browse and import models
• External Sources: Custom asset sources

Advanced Features

• Material Editing: Create and modify materials
• Texture Management: Apply and manage textures
• Python Scripting: Execute custom Blender scripts
• Batch Operations: Process multiple objects

Requirements

• Node.js: >= 18.0.0
• Blender: >= 3.0 (tested with 3.6+)
• Claude Desktop: Latest version
• OS: macOS, Windows, or Linux

Tips for End Users

Best Practices

1. Always start Blender before using Claude Desktop
2. Keep Blender console open to see real-time feedback
3. Save your work frequently - use "save the Blender file"
4. Use descriptive names for objects to make them easy to reference
5. Start with simple commands to verify connection

Example Workflows

Creating a scene:

1. "Create a cube in Blender"
2. "Add a sphere 5 units above the cube"
3. "Create a camera looking at the objects"
4. "Add a sun light to the scene"
5. "Take a screenshot of the viewport"

Working with materials:

1. "Create a red metallic material"
2. "Apply it to the cube"
3. "Make the sphere glass-like"

Asset integration:

1. "Search for HDRI sky on Poly Haven"
2. "Download the first result"
3. "Set it as environment texture"

Support

Getting Help

• Documentation: Check /docs folder for detailed guides
• Issues: Report bugs on GitHub Issues
• Logs: Always check Claude Desktop logs first

Reporting Bugs

Include:

1. Claude Desktop version
2. Node.js version (node --version)
3. Blender version
4. OS and version
5. Config file content (remove sensitive data)
6. Error logs from Claude Desktop
7. Blender console output

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - See LICENSE file for details

Acknowledgments

• Built with Model Context Protocol
• Integrates with Poly Haven
• Powered by Blender

Made with ❤️ by ClaudeKit Team