<p align="center">
  <img src="assets/logos/logo.svg" alt="ClaudeKit Blender MCP Logo" width="200">
</p>

<h1 align="center">ClaudeKit Blender MCP</h1>

<p align="center">
  <strong>Model Context Protocol server for Blender 3D integration with ClaudeKit enhancements.</strong>
</p>

<p align="center">
  <a href="#installation"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?style=flat-square" alt="Node.js"></a>
  <a href="#requirements"><img src="https://img.shields.io/badge/blender-%3E%3D3.0-orange?style=flat-square" alt="Blender"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a>
</p>

<p align="center">
  <a href="#installation">Installation</a> •
  <a href="#configuration">Configuration</a> •
  <a href="#available-tools">Tools</a> •
  <a href="#troubleshooting">Troubleshooting</a>
</p>

---

## 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)

```bash
npm install -g claudekit-blender-mcp
```

### Option 2: Local Development

```bash
# 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

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

#### Configuration for Local Development

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

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

Find your Node.js path:
```bash
# 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:**

```json
{
  "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):

```bash
# 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.

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

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

**Check Node.js version:**
```bash
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

```bash
# 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

```bash
# 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](https://modelcontextprotocol.io)
- Integrates with [Poly Haven](https://polyhaven.com)
- Powered by [Blender](https://www.blender.org)

---

**Made with ❤️ by ClaudeKit Team**