Overview

Blender MCP Server for Natural Language 3D Scenes is a lightweight HTTP service that translates natural language prompts into Blender-based 3D scenes. It automates common pipeline steps — scene generation, material assignment, lighting, camera placement, and rendering — so developers can create professional-looking renders without manually scripting Blender for every scenario.

The server implements the Model Context Protocol (MCP) pattern: a set of programmatic “tools” that convert intent into Blender operations. This lets you integrate natural-language scene creation into web apps, content pipelines, or automated testing systems while keeping Blender as the renderer and geometry engine.

Features

Natural language → Blender scenes: describe scenes in plain text and receive a rendered image or .blend file.
Programmatic tools for modeling, materials, lighting, camera, and rendering.
Headless Blender support for server-side rendering and batch jobs.
Configurable output formats: .blend, PNG/JPEG, GLTF export.
Simple REST API for integration with web services and automation jobs.
Extensible architecture: add custom tools or prompts to suit specific pipelines.

Installation / Configuration

Prerequisites:

Blender (recommended stable release) installed and available in PATH or configured via BLENDER_PATH.
Python 3.8+.

Quickstart:

# Clone repository
git clone https://github.com/pranav-deshmukh/blender-mcp.git
cd blender-mcp

# (Optional) create a virtual environment
python -m venv .venv
source .venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

Environment configuration (example):

# Example environment variables
export MCP_SERVER_PORT=8080
export BLENDER_PATH="/usr/bin/blender"   # path to Blender executable
export MCP_OUTPUT_DIR="./outputs"        # where .blend and renders are written
export MCP_MAX_RENDER_SAMPLES=64         # default render quality

Start the server:

# simple invocation (file name may vary in the repo)
python server.py --port ${MCP_SERVER_PORT:-8080}

Or run with an ASGI server:

uvicorn mcp_server.app:app --host 0.0.0.0 --port 8080 --workers 2

Note: The exact module / script name may vary; check the repository entry point if server.py is not present.

Available Tools

The MCP server exposes a set of domain tools (available programmatically and via the API) that encapsulate common operations:

Tool name	Purpose
model	Create primitives, combine meshes, import assets
material	Assign PBR materials, textures, and procedural shaders
light	Add and configure lights (area, sun, point, HDRI)
camera	Create cameras, set focal length and framing
layout	Arrange objects, snapping, and alignment helpers
render	Configure cycles/eevee settings and trigger renders
export	Save .blend, export GLTF/OBJ, and package assets

Each tool is implemented as an MCP “tool” allowing coordinated, multi-step transformations from a single prompt.

API Usage

Simple POST example to generate a scene and render an image:

curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist wooden coffee table on a rug in a sunlit living room, soft shadows, photorealistic",
    "options": {
      "resolution": [1920, 1080],
      "samples": 64,
      "style": "photoreal"
    }
  }'

Typical JSON response:

{
  "status": "ok",
  "blend_file": "outputs/session_2026-04-10_1234.scene.blend",
  "render_image": "outputs/session_2026-04-10_1234.render.png",
  "log": "Scene created with 12 objects. Render completed in 18.3s."
}

Endpoints you will commonly use:

POST /generate — create scene from a prompt and optionally render
POST /tools/{tool_name} — call a specific tool (model, material, render)
GET /status — server health and Blender availability

Use Cases

Rapid prototyping: designers describe scene concepts and receive renders without writing Blender Python. Example: “Create a product mockup: black matte smartphone on a concrete slab with soft studio lighting.”
Automated content generation: produce hundreds of environment variants (camera angles, materials) for dataset generation or marketing assets. Example: batch-create 50 renders of the same object with randomized HDRI and light temperature.
Pipeline integration: integrate into a web app that lets users generate concept scenes from chat prompts, then iterate by editing tool-specific parameters. Example: user adjusts “add warm rim light” which calls the light tool to modify existing scene lights.
Export for game assets: generate base geometry and export GLTF for downstream consumption.

Available Resources

Repository: https://github.com/pranav-deshmukh/blender-mcp
Output examples: check the repository’s outputs/ or examples/ directory for sample .blend and renders.
Configuration table:

Variable	Description	Default
BLENDER_PATH	Path to Blender executable	/usr/bin/blender
MCP_SERVER_PORT	HTTP port	8080
MCP_OUTPUT_DIR	Output directory for blends/renders	./outputs
MCP_MAX_RENDER_SAMPLES	Default sample count	64

Notes and Troubleshooting

Ensure Blender is accessible from the server account and has necessary add-ons enabled if you rely on third-party importers.
Headless rendering requires Blender’s command-line mode; check GPU drivers and available memory for heavy scenes.
For production, run the server behind a process manager and limit request sizes to avoid resource exhaustion.

This server is intended as a developer-focused automation layer between natural language prompts and Blender scenes. Extend the provided tools to match your project’s asset formats, rendering pipeline, and quality targets.