Meshwire

An independent MCP server for Blender. Control Blender from any MCP client, with tools for modeling, materials, sculpting, animation, AI 3D generation, and Microsoft Flight Simulator content.

Quick start · Tools · Self-refinement loop · Security · Documentation

Status, October 2026: a full audit found that many tools fail in real Blender, including every MSFS tool, most bake tools, and a group of mesh tools. Fixes are landing now and are tracked in the issues. Treat those areas as not working until the next release.

What is Meshwire?

Meshwire is an MCP server for AI clients such as Claude Desktop, Claude Code, and Codex CLI. The server speaks the Model Context Protocol over stdio. A Blender addon listens on a local TCP socket and runs each command on Blender's main thread through bpy.app.timers.

┌─────────────────┐    stdio     ┌─────────────────┐   TCP/JSON-RPC   ┌─────────────────┐
│  MCP client     │ ◄──────────► │   MCP Server    │ ◄──────────────► │  Blender Addon  │
│  (Claude / …)   │              │  (Python proc)  │   port 9876      │  (bpy.app.timers)│
└─────────────────┘              └─────────────────┘                  └─────────────────┘

• Blender coverage: scene, object, mesh, material, modifier, animation, render, export, baking, geometry nodes, sculpting, rigging, physics, and annotations.
• MSFS content: LOD, collision, material, animation, and livery tools for Microsoft Flight Simulator. This area is being rebuilt and does not work in the current release.
• AI 3D generation: text and image to 3D through Hyper3D Rodin, Meshy, Tripo, TripoSR, Stable Fast 3D, Hunyuan3D, and ComfyUI.
• Self-refinement loop: render an object from several angles, score it with an Ollama vision model, and iterate.
• Poly Haven: free HDRIs, textures, and models with no API key.

Quick start

1. Run the MCP server

Meshwire is in alpha, so ask for pre-releases. With uv there is nothing to install up front:

uvx --prerelease allow meshwire --help

Or with pip:

pip install --pre meshwire

2. Install the Blender addon

Download blender_mcp_addon-<version>.zip from Releases, or build it from source:

git clone https://github.com/RFingAdam/meshwire
cd meshwire
python scripts/package_addon.py
# creates dist/blender_mcp_addon-<version>.zip

In Blender, open Edit > Preferences > Add-ons, choose Install from Disk from the menu at the top right, select the ZIP, and enable Meshwire.

3. Configure your MCP client

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["--prerelease", "allow", "meshwire"]
    }
  }
}

If you installed with pip, use "command": "meshwire" with no args.

4. Connect

1. In Blender's 3D viewport, press N and open the MCP Server tab.
2. Click Start Server.
3. Restart your MCP client. The Blender tools appear in its tool list.

Then try:

Create a red cube at (2, 0, 0), add a subdivision surface modifier with 2 levels, and render it to /tmp/render.png.

Tools

The server defines 218 tools. This table lists what exists, not what has been verified to work; see the status note above. The tool list is in docs/tools.md.

Every tool name takes a blender_ prefix, for example blender_scene_info.

Self-refinement loop

The agent writes mesh code, renders from several angles, an Ollama vision model scores the result, and the agent applies fixes until the score stops improving.

┌───────────┐  execute_script  ┌─────────┐  render_multi_angle  ┌──────────────┐
│  agent    │ ──────────────► │ Blender  │ ───────────────────► │  PNG images  │
│  (LLM)    │                 │  (bpy)   │                      └──────┬───────┘
└─────┬─────┘                 └─────────┘                              │
      │                                                  analyze_viewport
      │  apply fix                                                     │
      │  (loop)                                                        ▼
      │                                                     ┌──────────────────┐
      └─────────────────────────────────────────────────────│  Ollama Vision   │
                              feedback + score              │ llama3.2-vision  │
                                                            └──────────────────┘

# 1. Open a refinement session
blender_refine_create_session(object_name="Tree", prompt="A realistic low-poly pine tree")

# 2. Generate an initial mesh
blender_execute_script(script="import bmesh; ...")

# 3. Evaluate
blender_refine_iteration(object_name="Tree", iteration=0, max_iterations=5)

# 4. Apply fixes from the feedback, then evaluate again
blender_execute_script(script="# fix issues from analysis ...")
blender_refine_iteration(object_name="Tree", iteration=1, previous_score=0.6)

# 5. Inspect the session
blender_refine_get_session(session_id="...")

See docs/usage.md for a walkthrough.

External integrations

Poly Haven

Poly Haven provides free HDRIs, textures, and 3D models with no API key. Downloads are cached locally.

blender_polyhaven_search(query="brick", asset_type="textures")
blender_polyhaven_download(asset_id="brick_wall_001", resolution="2k")

AI 3D model generation

Cloud setup:

export RODIN_API_KEY="your-rodin-key"
export MESHY_API_KEY="your-meshy-key"
export TRIPO_API_KEY="your-tripo-key"

Local setup:

# TripoSR is not on PyPI: clone it and put it on PYTHONPATH
git clone https://github.com/VAST-AI-Research/TripoSR
pip install -r TripoSR/requirements.txt
export PYTHONPATH="$PWD/TripoSR:$PYTHONPATH"

ollama pull llama3.2-vision:11b   # vision model for evaluation and refinement

Usage:

blender_ai_generate_model(prompt="a wooden chair", style="realistic")
blender_ai_generate_model(image_path="/path/to/image.png")
blender_ai_model_status(job_id="abc123", auto_import=true)

Styles: realistic, cartoon, low_poly, sculpture, anime. Formats: glb (default), gltf, fbx, obj, usdz.

Security

The addon's socket has no authentication yet, and blender_execute_script runs arbitrary Python inside Blender. Any process on your machine that can reach the port can run code as you.

• Only start the server on a machine you trust, and stop it when you're done.
• Keep the host set to localhost. Don't bind it to 0.0.0.0 or expose port 9876.
• Don't run untrusted prompts or scripts against a Blender session with work you care about.

Authentication and a Python execution switch are planned for the next stable release (#12).

Configuration

meshwire [--host HOST] [--port PORT]

  --host HOST   Blender addon host (default: 127.0.0.1)
  --port PORT   Blender addon port (default: 9876)

The Meshwire tab in Blender's sidebar sets the socket port and starts or stops the server.

Blender versions

Blender 4.5 LTS and 5.2 LTS are tested on every pull request. Blender 4.2 LTS is tested nightly on a best-effort basis.

Troubleshooting

"Connection refused": make sure Blender is running, the MCP Server tab shows the server running, and the port matches.

"Tool not found": restart your MCP client after editing its config, confirm the server command runs on its own with --help, and check the client's MCP log.

Addon doesn't appear in Blender: check Blender's system console for errors and try reinstalling the ZIP.

Poly Haven downloads fail: check your connection, confirm the asset ID exists on polyhaven.com, and check disk space.

AI generation doesn't work: blender_ai_list_backends shows backend status. Check your API keys for cloud backends, or your models and VRAM for local ones. Follow a job with blender_ai_model_status.

Documentation

• Quick start: install through first call.
• Tool reference: tools grouped by stage.
• Usage examples: self-refinement, MSFS, and livery walkthroughs.
• Architecture: how the server and addon fit together.
• MSFS roadmap: planned MSFS workflow.

Development

git clone https://github.com/RFingAdam/meshwire
cd meshwire
python -m venv .venv
source .venv/bin/activate   # .venv\Scripts\activate on Windows
pip install -e ".[dev]"

pytest tests/ --ignore=tests/blender_integration_test.py   # unit tests
python -m tests.harness.driver --help   # truth harness, needs Blender; see CONTRIBUTING.md
ruff check .
ruff format .
python scripts/package_addon.py   # builds the addon ZIP

Contributions are welcome. See CONTRIBUTING.md.

License

AGPL-3.0-or-later.

Trademarks

This project is not affiliated with, endorsed by, or sponsored by the Blender Foundation. "Blender" is a trademark of the Blender Foundation, used here only to identify the software this project works with.

Acknowledgments

• Blender Foundation for Blender.
• Poly Haven for free 3D assets.
• Hyper3D Rodin, Meshy.ai, Tripo, TripoSR, Stable Fast 3D, Hunyuan3D, and ComfyUI for AI 3D backends.
• The MCP working group for the Model Context Protocol.

Trademarks

Meshwire is an independent project. It is not affiliated with, endorsed by, or sponsored by the Blender Foundation, Microsoft, or Asobo Studio. Blender is a registered trademark of the Blender Foundation. Microsoft Flight Simulator is a trademark of Microsoft Corporation. These names are used only to say what Meshwire works with.