Blender-AI-Agent
Local-first AI-to-3D pipeline: LLM planning, validated Blender generation behind an MCP tool boundary, read-only vision review, semantic motion, and GLB/MP4 export with a FastAPI + Three.js studio.
Install / Use
claude mcp add ahmedsayed1911 -- npx -y github:ahmedsayed1911/Blender-AI-AgentIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AutomationSupported Platforms
Our assessment of Blender-AI-Agent
Blender-AI-Agent scores 83/100 on our quality scale, 2123rd of 2,771 Automation skills we index.
Its MCP Server is 7.0 KB long, well organised into 17 sections with 11 code examples: a thorough specification that gives an agent plenty to work with.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated about 3 months ago, so Blender-AI-Agent is actively maintained.
- It is released under GPL-3.0, a copyleft license: you can use it, but modified versions you distribute must carry the same license.
- Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Blender-AI-Agent compared with similar skills
All 4 of these similar skills score higher than Blender-AI-Agent; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| Blender-AI-Agent (this skill)by ahmedsayed1911 | 83 | 10 | 3mo ago | MCP Server |
| Agent-Reachby Panniantong | 100 | 112.7k | 10d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 82.0k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.9k | today | CLAUDE.md |
| CowAgentby zhayujie | 100 | 48.0k | 1d ago | CLAUDE.md |
Frequently asked questions
- How do I install Blender-AI-Agent?
- Run
claude mcp add ahmedsayed1911 -- npx -y github:ahmedsayed1911/Blender-AI-Agent. The install tabs above show the steps for each supported agent. - Which AI agents does Blender-AI-Agent work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is Blender-AI-Agent safe to use?
- It is GPL-3.0-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is Blender-AI-Agent still maintained?
- The repository was last updated about 3 months ago, so Blender-AI-Agent is actively maintained.
Skill content
View source on GitHubBlender AI Agent
A local, safety-oriented AI-to-3D pipeline that connects LLM planning, Blender generation, visual review, semantic motion, artifact export, and a browser-based Web Studio.
The project uses MCP (Model Context Protocol) as the tool boundary between the AI layer and Blender. The model does not get unrestricted bpy or arbitrary Python execution during normal operation; it plans against validated, allowlisted tools.
What it does
Prompt
↓
LLM planning
↓
Semantic structure / generation blueprint
↓
Controlled geometry + refinement
↓
Blender via MCP bridge
↓
Read-only vision review
↓
Semantic motion / animation
↓
PNG + GLB + MP4 artifacts
↓
FastAPI + React / Three.js Web Studio
Current capabilities include:
- Prompt-driven semantic 3D generation
- Reusable geometry and refinement systems
- Creature, robot, vehicle, prop, and architecture workflows
- Read-only visual critique with Qwen-VL
- Semantic articulation and motion planning
- Dragon wing, tail, locomotion, and reference-inspired motion experiments
- Robot walking and articulated arm actions
- Spaceship / prop / architecture presentation motion
- Controlled preview, GLB, and H.264 MP4 artifact generation
- Job orchestration, revisions, confirmation, rollback, and artifact tracking
- FastAPI backend and React + Three.js Web Studio
This is an experimental procedural 3D system, not a production sculpting or game-asset pipeline. Geometry and locomotion quality are still being actively improved.
Core idea
A normal LLM tool call is the easy part. The harder problem is building a system around the model that is structured, controllable, measurable, and safe.
This repository therefore keeps Blender mutation behind typed tools, validation, ownership, confirmation, and rollback rather than exposing arbitrary scene scripting.
Architecture
User / Web Studio
│
▼
FastAPI / Job Runtime
│
▼
LLM Planner (Ollama / Qwen)
│
▼
Generation + Refinement + Motion Engines
│
▼
MCP Tool Layer
│
▼
Socket Bridge
│
▼
Blender Runtime
│
├── PNG previews
├── GLB exports
└── MP4 renders
Read-only Vision (Qwen-VL) reviews rendered output but does not mutate Blender directly.
Main packages
| Package | Purpose |
|---|---|
| core/ | shared models, configuration, DI, tools, bridges, validation |
| mcp_server/ | MCP tool registration and server boundary |
| mcp_client/ | MCP client / smoke paths |
| blender_addon/ | Blender-side runtime and controlled scene operations |
| generation_engine/ | generation planning and compilation |
| general_3d_engine/ | reusable semantic composition / recipes / camera logic |
| geometry_engine/ | controlled geometry representation and planning |
| shape_refinement_engine/ | refinement policies, articulation readiness, efficiency |
| anatomy_engine/ | reusable anatomy/layout systems |
| animation_engine/ | controlled animation/video primitives |
| motion_engine/ | semantic motion, interpolation, chains, validation, sequencing |
| reference_engine/ | reference-video motion analysis and style extraction |
| vision_engine/ | read-only visual critique and comparison |
| platform_runtime/ | projects, jobs, revisions, artifacts, workers |
| web_backend/ | FastAPI API, SSE, artifact delivery |
| web_studio/ | React/Vite product UI |
| web_viewer/ | Three.js viewer utilities |
| tests/ | unit and Blender integration validation |
Requirements
- Windows is the most-tested development environment
- Python 3.11+
- Blender 5.x (parts of the add-on are compatible with 4.2+)
- Node.js + npm
- Ollama
Python dependencies:
python -m pip install -r requirements.txt
Frontend dependencies:
cd web_studio
npm install
Local models
Model weights are not stored in this repository. Install them locally with Ollama.
Example setup:
ollama pull qwen3-coder-next:latest
ollama pull qwen3-vl:8b
Optional larger vision audit model:
ollama pull qwen3-vl:32b
The exact model names can be changed through runtime configuration / environment variables.
Quick start
1. Start the Blender bridge
From the repository root, use the bridge runtime appropriate for your local Blender installation. A development example is:
$env:BAA_BLENDER_PORT="8770"
& "C:\path\to\blender.exe" --background --factory-startup --python "tests\blender\run_bridge_runtime.py"
Do not copy that Blender path literally; point it at your own installation.
2. Start the API
Open a second terminal:
cd C:\path\to\Blender-AI-Agent
$env:BAA_BLENDER_PORT="8770"
python -m uvicorn web_backend.app:create_app --factory --host 127.0.0.1 --port 8000
3. Start Web Studio
Open a third terminal:
cd C:\path\to\Blender-AI-Agent\web_studio
npm.cmd run dev
Vite will print the local Web Studio URL (commonly http://127.0.0.1:5174/).
Tests
Python:
python -m pytest -q
python -m unittest discover -s tests -v
Frontend:
cd web_studio
npm.cmd run test
npm.cmd run build
Blender integration validators live under tests/blender/ and require a compatible Blender runtime.
Safety model
Normal operation intentionally avoids exposing:
- arbitrary model-generated Python
- unrestricted
bpy - unrestricted Blender operators / BMesh
- arbitrary F-curves, drivers, or constraints
- arbitrary filesystem paths
- arbitrary FFmpeg arguments
Instead, the project uses bounded semantic structures and allowlisted tools with validation, revision ownership, confirmation, and rollback.
Vision remains read-only.
Generated data
The following are intentionally excluded from Git:
- Ollama / Qwen model weights
node_modules- generated
artifacts/ - runtime SQLite databases
- logs and caches
- Blender autosaves
- environment / secret files
See .gitignore.
Documentation
Detailed implementation notes are under docs/, including geometry, animation, vision feedback, backend/API, Web Studio, GLB export, safety-oriented generation, and migration notes.
Project status
This is an active experimental project. The repository currently demonstrates an end-to-end local AI → Blender → Vision → Motion → Web workflow, while areas such as higher-fidelity modeling, contact-aware IK, motion polish, and richer interactive animation export remain ongoing work.
License
GNU General Public License v3.0.
blender_addon/ imports bpy and registers through bl_info, which makes it
a Blender add-on rather than an independent program. Blender is GPL-licensed
and the Blender Foundation treats add-ons that import bpy as needing to be
GPL-compatible, so the repository is released under GPL-3.0 to stay clearly
within those terms.
Third-party components keep their own licences and none are vendored here: Blender (GPL), Ollama and the Qwen models it serves, FastAPI, React, and Three.js.
Related Skills
Agent-Reach
112.7kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
82.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.9kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
CowAgent
48.0kOpen-source personal AI assistant & Agent Harness. Plans tasks, runs tools and skills, self-evolves with memory and knowledge. Multi-agent, multi-model, multi-channel. Lightweight, extensible, one-line install.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
