Metadata-Version: 2.4
Name: blender-mcp-connect
Version: 0.1.0
Summary: MCP server for Blender with automatic local instance discovery (unofficial downstream of Blender Lab MCP)
Author: marble810
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/marble810/blender-mcp-connect
Project-URL: Repository, https://github.com/marble810/blender-mcp-connect
Project-URL: Issues, https://github.com/marble810/blender-mcp-connect/issues
Project-URL: Changelog, https://github.com/marble810/blender-mcp-connect/blob/main/CHANGELOG.md
Project-URL: Upstream, https://projects.blender.org/lab/blender_mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: docutils
Requires-Dist: mcp[cli]<2,>=1.2
Requires-Dist: pyyaml

# Blender MCPB Extension

## Description
A lightweight MCP (Model Context Protocol) server for Blender.

Allows LLM assistants to interact with a running Blender instance – inspecting scenes, executing Python code, rendering, and navigating the interface.

## Features
It supports running arbitrary Python code within Blender. This allows for advanced scene analysis and debugging. It also contains the complete API and user manual as resources, helping the LLM to access the latest version of both documentations.

## Installation

The MCP Server is published to PyPI as `blender-mcp-connect` and is
installed via `uvx` (or `pip install blender-mcp-connect`).

It requires an add-on in Blender for this to work:

### Add-on

* Install the **MCP Connect** Blender Extension from the
  [GitHub Releases](https://github.com/marble810/blender-mcp-connect/releases)
  page (**Preferences → Get Extensions → Install from Disk…**).
* Enable the add-on.

> **Note:** this is an unofficial community downstream of Blender Lab MCP.
> Do not install both the official Blender Lab MCP add-on and MCP Connect at
> the same time; they would both try to serve the same bridge role.

### MCP client configuration

```json
{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": [
        "--from",
        "blender-mcp-connect==0.1.0",
        "blender-mcp-connect"
      ]
    }
  }
}
```

## Examples

You can find more examples in the [documentation](https://www.blender.org/lab/mcp-server/).

### Example 1: Data-block renaming: fix types

**Demo file**: [Pebble Scattering](https://www.blender.org/download/demo/geometry-nodes/fields/pebble_scattering.blend)

**User prompt**: "With the current open Blender file fix the name of all the data-blocks to remove typos. Report back which data-blocks got fixed."

**Expected behaviour:**
- `GRP-rocks` → `GRP-pebble` [optionally, this is more opiniated]
- `LGT-Lights` → `LGT-lights`
- `Compositing Nodetree` → `Compositing Node Tree`

### Example 2: Querying data relations using natural language

**Demo file**: [Pebble Scattering](https://www.blender.org/download/demo/geometry-nodes/fields/pebble_scattering.blend)

**User prompt**: "Which objects are using the following material: pebbles"

**Expected behaviour:**
7 objects:
- `GEO-pebble`
- `GEO-pebble.001`
- `GEO-pebble.002`
- `GEO-pebble.003`
- `GEO-pebble.004`
- `GEO-pebble.005`
- `GEO-pebble.006`

### Example 3: Querying data relations using natural language

**Demo file**: [Classroom](https://download.blender.org/demo/test/classroom.zip)

**User prompt**: "Analyze the scene and list the outliers: objects with highest polygon count but smaller size from the camera point of view."

**Expected behavior:**
An analysis that consider the final amount of polygons after the object modifiers are applied. This usually happens by getting the object from the dependency graph.

The biggest outliers are: `coat 1` and `alphabet`.

Depending on whether or not the RENDER context was used (as oppose to the VIEWPORT context), the biggest outlier (`coat 1`) may show 37k or 74k polygons. This is the only object that has a modifier which is only used for rendering. Every other object should report the same poly-count regardless of the context.

## Privacy Policy
See our privacy policy: https://www.blender.org/privacy-policy/

## Support
For issues: https://projects.blender.org/lab/blender_mcp/issues
