MCP-Based Intelligent 3D Modeling Agent

Drive Blender with an AI Agent—218 MCP tools covering the full 3D pipeline, plus a LangGraph Agent intelligence layer: a plan→execute→observe→review→replan closed loop, versioned Prompts, schema-gated tool selection, and a reproducible Benchmark.

🌏 English: README.en.md

What This Project Demonstrates · Architecture · Benchmark Results · Quick Start · Documentation

Overview

This repository consists of two layers:

1. MCP Foundation Layer (based on upstream RFingAdam/mcp-blender, eng-mcp-suite) — an MCP server that exposes 218 Blender tools (modeling, materials, modifiers, animation, rendering, sculpting, geometry nodes, physics, AI 3D generation, MSFS content pipeline) to any MCP client.

2. Agent Intelligence Layer (agent/ directory, original work of this repository) — a LangGraph-based 3D Agent: plans tasks, executes via MCP tools, collects scene facts, verifies acceptance criteria one by one (evidence required), applies minimal fixes—with versioned Prompts, structured output contracts, evaluation logs, and a 16-task Benchmark.

What This Project Demonstrates

Complete engineering practice—making LLM Agents reliable, measurable, and engineerable.

Architecture

┌───────────────┐   MCP stdio    ┌────────────────┐   TCP JSON-RPC   ┌──────────────────┐
│  MCP client   │ ◄────────────► │  MCP server    │ ◄──────────────► │  Blender addon   │
│ (Claude Code) │                │  (Python 进程)  │   localhost:9876 │  (bpy.app.timers)│
└───────────────┘                └────────────────┘                  └──────────────────┘

The Agent layer is a fourth process that runs as an MCP client of the existing MCP server—never reimplementing any Blender tool:

用户 / LLM 客户端
  │
  ▼
★ LangGraph Agent（agent/）          ← 本项目的智能层
  │   MCP 客户端（stdio）—— 复用全部 218 个工具
  ▼
mcp-blender MCP server（上游，零修改）
  │
  ▼
Blender addon → bpy → Blender 场景

Agent Loop

START → Planner → Executor → Observer → Reviewer → Router ── 通过 ──► END
                                                       └─ 重规划 ──► RePlanner → Executor（循环）

Reliability is enforced by code, not by Prompt discipline: schema validation + one Tool Selection Repair retry, mandatory criteria coverage, and any parse failure explicitly degrades (recorded in state, exposed to the Reviewer—never silent).

Live Demo

Benchmark Results

Tested on a real Blender 4.x instance—the Agent executed all 16 tasks in benchmarks/tasks.json (4 difficulty levels, from basic creation to composite modeling), with evidence-based acceptance for each task.

L3–L4 composite modeling tasks (table, house, snowman, boolean hole, pine tree, chair, teacup, robot) all passed geometric evidence acceptance—for example, the robot's 1012 vertices exactly equal the sum of vertices of 6 cubes + 2 spheres.

Methodology note: Claude as the Agent executed against real Blender via the addon's JSON-RPC channel (the same transport layer used by the MCP server); per-task records are in eval_runs/ and docs/PHASE2_PROMPT_ENGINEERING.md. The Benchmark also uncovered a real addon defect (scene_clear cannot clear hidden objects → duplicate-name object conflicts), recorded in the documentation's findings log—which is exactly the purpose of having an evaluation system.

Quick Start

1. Installation

git clone https://github.com/SekaiNoOwari77/mcp-3d-modeling-agent.git
cd mcp-3d-modeling-agent
pip install -e .                       # MCP server（基础层）
pip install -r agent/requirements.txt  # Agent 层（langgraph、mcp、httpx、jsonschema）

2. Start Blender

1. Install the addon: Blender → Edit → Preferences → Add-ons → Install… → select addon/blender_mcp_addon (can be packaged as a ZIP with python scripts/package_addon.py, or symlink the directory directly).

2. Enable "MCP Server Addon".

3. In the 3D viewport press N → MCP Server panel → Start Server (default port 9876).

3. Use as an MCP tool provider (any MCP client)

{
  "mcpServers": {
    "blender": { "command": "mcp-blender", "args": ["--port", "9876"] }
  }
}

Then simply tell the client: "Create a red cube at (2, 0, 0), add a Subdivision Surface modifier with 2 levels."

4. Run the LangGraph Agent

AGENT_LLM_MODEL=deepseek-chat \
AGENT_LLM_BASE_URL=https://api.deepseek.com/v1 \
AGENT_LLM_API_KEY=sk-... \
python -m agent.run "做一个低多边形松树：圆柱树干加三层圆锥树叶"

Arguments: --render (enable observation rendering), --max-iterations, --prompt-version, --no-eval, -v. Metrics persisted to: eval_runs/eval_runs.jsonl + eval_runs/records/.

5. Run the Benchmark

python -m benchmarks.runner                   # 全部 16 个任务
python -m benchmarks.runner --levels 1,2      # 按难度级别
python -m benchmarks.runner --tags regression # Phase-1 回归任务

Repository Structure

src/mcp_blender/            MCP server：218 个工具定义 + Blender TCP 客户端      （上游）
addon/blender_mcp_addon/    Blender 插件：socket 服务器、handlers、AI 后端       （上游）
agent/                      ★ Agent 智能层（原创）
├── graph.py                LangGraph 组装（6 节点 + plan 级循环）
├── state.py                Plan / PlanStep / Criterion / ReviewVerdict 数据结构
├── config.py               env 驱动的配置
├── execution.py            任务执行入口（CLI 与 benchmark 共用）
├── llm.py                  OpenAI 兼容 LLM 客户端，带 token 用量追踪
├── nodes/                  planner / executor / observer / reviewer / replanner / router
├── prompts/                版本化 Prompt 模板（planner/v1.md 等）
├── context/                每节点上下文构建器
├── evaluation/             EvalLogger：11 项指标，JSON + JSONL 记录
└── tools/mcp_client.py     MCP 客户端：子进程生命周期、目录缓存、串行调用
benchmarks/                 16 任务 benchmark 套件 + runner + 传输 shim
tests/                      基础层测试 + tests/agent/（单元 + 假 LLM 端到端循环）
docs/                       工具参考、使用示例、架构、Agent 设计文档

Testing

pytest tests/agent -q                    # Agent 层：44 个测试
PYTHONPATH=src pytest tests/ --ignore=tests/blender_integration_test.py  # 基础层：84 个测试

Includes fake-LLM end-to-end graph tests: full convergence loop, Tool Selection Repair recovery path, and explicit handling of Reviewer parse failures.

Documentation

• docs/tools.md — complete reference for the 218 MCP tools

• docs/usage.md — end-to-end usage examples

• docs/architecture.md — MCP/server/addon architecture

• docs/AGENT_ARCHITECTURE.md — Agent layer design (Phase 1, Chinese)

• docs/PHASE2_PROMPT_ENGINEERING.md — Prompt system, Schema, evaluation and Benchmark methodology, real test results, findings log (Chinese)

• docs/MSFS_ROADMAP.md — MSFS content pipeline

Roadmap

• Phase 3 — Tool RAG: retrieve candidate tools per task, replacing the current approach of injecting the full 218-tool catalog; current metrics serve as the comparison baseline.

• Phase 4 — Visual review and memory: multimodal Reviewer based on the existing analyze_viewport tool; cross-session memory.

• Wrap the Agent itself as an MCP server (exposing a single run_3d_task tool) for higher-level clients to call.

License and Acknowledgments

• This repository: AGPL-3.0-or-later.

• Upstream foundation: RFingAdam/mcp-blender (part of eng-mcp-suite) — the MCP server, Blender addon, and 218 tools come from the upstream project; the Agent intelligence layer (agent/), evaluation system, Benchmark, and Agent documentation are original contributions of this fork.

• Blender itself remains GPL-licensed, invoked only at runtime, and is not distributed with this repository.

LangGraph · MCP · Prompt Engineering · Evaluation System.