# Python Automation Service for Blender

A Python MCP server that connects an AI client to a running Blender desktop application through a local TCP bridge. It exposes reusable tools for scene inspection, rendering, asset export, visual comparison, and controlled mesh operations.

## Engineering focus

- Separate server, connection, visual-review, and sculpting modules.
- Validate inputs and sanitize export paths before forwarding commands.
- Provide project checkpoints and explicit operation limits.
- Include portable setup, connection diagnostics, and troubleshooting documentation.
- Cover non-Blender logic with automated tests, without requiring a running Blender instance.

## Architecture

```text
MCP client -> Python MCP server (stdio) -> local TCP bridge -> Blender add-on
                         |                                 |
                   input validation                 Blender main thread
```

## Quick start

Requires Python 3.10+, uv, Blender, and an MCP-compatible client. The bundled launcher and setup helpers target macOS and Claude Code; other environments require manual client and Blender configuration.

```sh
uv sync
./bin/blender-mcp-setup.py --dry-run
./bin/blender-mcp-setup.py
./bin/blender-resolve.sh --gui
./bin/blender-mcp-health.py
```

Review setup output before enabling the integration. The setup helper writes project-local configuration; it does not modify global client settings. See [usage and troubleshooting](docs/usage.md).

## Tests

```sh
uv sync
PYTHONPATH=src uv run python -m unittest discover -s tests -v
```

Validation on November 4, 2026: **299 tests passed** with the development environment. These tests cover non-Blender logic and do not establish end-to-end Blender compatibility on every machine.

Example workflow: inspect the current scene, save a checkpoint, render multiple views, compare a render with a local reference, then export an asset. The detailed [smoke-test recipe](scripts/smoke_torus_knot.md) requires a running Blender instance.

## Scope and safety

This is a local desktop integration, not a hosted web API. The add-on can execute Python inside Blender and should be used only with trusted clients and commands. Keep the socket bound to localhost; do not expose it to untrusted networks. Retrying a command after a broken connection can repeat an operation. Save checkpoints before modifying important scenes.

## Attribution

Adapted from the MIT-licensed [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp) foundation. This version adds the validation, review, sculpting, setup, and testing layers described above. See [NOTICE.md](NOTICE.md) and [LICENSE](LICENSE).