Meshwire

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: every pull request runs each tool in real Blender 4.5 LTS and 5.2 LTS. 190 of 225 tools work on both. 35 need what a headless test cannot provide, such as a GUI, network access, or an earlier call. Each list is under Tools, and fixes are tracked in the issues.

---

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)  │  9876 to 9885    │  (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. These tools now run in the test harness, but no generated package has been loaded in the sim yet, so treat their output as unproven until it has.
• 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

With uv there is nothing to install up front:

uvx meshwire --help

Or with pip:

pip install meshwire

2. Install the Blender addon

Download meshwire-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/meshwire-addon-<version>.zip

In Blender, open Edit > Preferences > Get Extensions, open the dropdown arrow at the top right, choose Install from Disk..., and select the ZIP. Blender installs it as an extension and enables Meshwire. Host, port and API keys are add-on preferences, stored per user, so a shared .blend file carries none of them. Do not unzip the file first.

If you installed Meshwire before 0.5.0, remove the old copy first (Edit > Preferences > Add-ons, Meshwire, Remove) and restart Blender. Two copies enabled together would start two servers, so the new one shows a warning in its sidebar tab and does not start while the old one is enabled.

execute_script is off until you turn it on. Open the Meshwire tab in the 3D Viewport sidebar and click Allow Python. It stays on until Blender closes and is off again at every start.

3. Configure your MCP client

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["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 Meshwire 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

Each tool is run in headless Blender with valid input, with every value of each enum, and with no arguments at all. A tool counts as working when every valid call succeeds or returns the error it should. That does not prove the output is right, so a second test drives Blender through the real socket and checks the result for core tools such as object creation, render, and bake. The numbers below are generated from the test baselines by scripts/tool_status.py, and a test fails if they drift. More detail per area is in docs/tools.md.

Area	Tools	Work on 4.5	Work on 5.2	Examples
Scene	5	5	5	scene_info, scene_new
Objects	13	13	13	object_create, object_duplicate
Mesh, curves, booleans	38	35	35	mesh_bevel, curve_create
Materials and nodes	13	13	13	material_create, material_inspect_graph
Modifiers	5	5	5	modifier_add, modifier_apply
Animation	7	7	7	keyframe_delete, action_create
Render	6	5	5	render_image, render_multi_angle
Import and export	6	6	6	export_fbx, export_usd
Measurement and validation	7	7	7	measure_volume, measure_clearance
Baking	6	6	6	bake_pbr_batch, bake_from_multires
Geometry nodes	7	7	7	geonode_array_grid, geonode_extrude_profile
Sculpting	8	4	4	sculpt_setup, sculpt_remesh_voxel
Rigging	8	8	8	armature_create, autorig_preset
Physics	6	6	6	physics_rigid_body_add, physics_cloth_add
Collections and session	8	6	6	collection_create, save_as
Annotations	6	5	6	annotation_dimension, annotation_text
MSFS content	20	20	20	msfs_create_lod_hierarchy, msfs_setup_material
MSFS livery	18	15	15	msfs_livery_transfer, msfs_livery_create_package
AI generation and refinement	36	17	17	ai_mesh_remesh, ai_auto_uv
Poly Haven	2	0	0
Total	225	190	191

35 tools that cannot be checked headless

Where a reason names the socket lane, it runs on Blender 4.5 and 5.2 on every pull request, and on 4.2, 4.3, 4.4, 5.0 and 5.1 nightly, best effort.

Tool	Why
ai_cancel_generation	needs a job id that only a live AI backend can issue
ai_evaluate	needs network access, which the harness turns off
ai_generate_model	no AI backend is reachable offline
ai_generate_model_sync	no AI backend is reachable offline
ai_generate_reference_image	no AI backend is reachable offline
ai_generate_texture	no AI backend is reachable offline
ai_generate_texture_sync	no AI backend is reachable offline
ai_generate_variations	no AI backend is reachable offline
ai_inpaint_texture	no AI backend is reachable offline
ai_model_status	needs a job id that only a live AI backend can issue
ai_pipeline_generate	no AI backend is reachable offline
ai_pipeline_status	needs a pipeline id that only a live AI backend can issue
ai_probe_backends	needs network access, which the harness turns off
ai_redo_generation	needs a previous generation, which only a live AI backend can produce
ai_refine	needs network access, which the harness turns off
ai_texture_from_render	no AI backend is reachable offline
analyze_viewport	needs network access, which the harness turns off
annotation_add	Blender 4.3 to 5.1 offers no Python call that creates an annotation stroke, so the tool says so; the socket test annotation_add_draws_or_says_why checks both outcomes
mesh_edge_slide	needs a 3D viewport; socket lane covers it
mesh_knife_project	needs a 3D viewport; socket lane covers it
mesh_loop_cut	needs a 3D viewport; socket lane covers it
msfs_livery_convert_to_dds	needs texconv from DirectXTex, which is not installed here
msfs_livery_export_uv_layout	the UV exporter draws on the GPU, which background mode lacks; the socket test checks it in a GUI
msfs_livery_set_paint_brush	needs texture paint mode from a prior msfs_livery_setup_paint_mode call, which a fresh-scene case cannot make; the socket test msfs_paint_brush_after_setup runs both
polyhaven_download	needs network access, which the harness turns off
polyhaven_search	needs network access, which the harness turns off
redo	Blender disables undo in background mode
refine_get_session	needs a session id from a prior refine_create_session call
refine_iteration	needs network access, which the harness turns off
render_screenshot	needs a 3D viewport; socket lane covers it
sculpt_face_set_create	face_sets_init crashes Blender in background mode, so it needs a 3D viewport; socket lane covers it
sculpt_mask_by_topology	the mask operators need a 3D viewport and crash Blender in background mode; socket lane covers it
sculpt_mesh_filter	needs a 3D viewport; socket lane covers it
sculpt_multires_reshape	the fixture mesh has no subdivision levels to rebuild or unsubdivide
undo	Blender disables undo in background mode

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

Backend	Type	Requirements	Capabilities
Hyper3D Rodin	Cloud	API key	Text-to-3D, Image-to-3D
Meshy.ai	Cloud	API key	Text-to-3D, Image-to-3D, texturing
Tripo AI	Cloud	API key	Text-to-3D, Image-to-3D
TripoSR	Local	4 GB VRAM	Image-to-3D
Stable Fast 3D	Local	6 GB VRAM	Image-to-3D
Hunyuan3D	Local	16 GB VRAM	Text-to-3D, Image-to-3D
ComfyUI	Local	Varies	Custom workflows

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 add-on's socket needs a token. On first start the add-on makes one in the Meshwire config folder (~/.config/meshwire/token on Linux, mode 0600) and the server reads it on every connect, so on one machine there is nothing to set up. A connection must open with a hello within 2 seconds and prove it holds the token by HMAC-SHA256 over fresh nonces. The token itself never crosses the socket. Anything else is closed. For a server on another machine, set MESHWIRE_TOKEN there and use Copy token in the Meshwire tab. To revoke a token, see "Rotating the token" in SECURITY.md.

blender_execute_script runs arbitrary Python inside Blender, so it refuses every call until you click Allow Python in the Meshwire sidebar tab. Only that button turns it on, and nothing a client sends or a .blend file holds can. It resets whenever Blender starts.

• The token does not stop other programs running as you. They can read the file, so they can connect.
• After the handshake the traffic is not encrypted or integrity-protected. Keep the host at localhost. If you bind the add-on to a non-loopback address, commands and results travel in plaintext, so anyone on the network path can read or change them. For remote use, tunnel over SSH instead.
• Don't run untrusted prompts or scripts against a Blender session with work you care about.

Every version before 0.5.0 (the releases were 0.2.0, 0.3.0, 0.4.0 and 0.5.0a1) had no authentication: any process that could reach the port, including a web page sending an HTTP POST, could drive Blender, and execute_script ran any Python it was sent. Upgrade, and see SECURITY.md for what was confirmed and how to report a problem.

blender_ai_configure_backend accepts only enabled, api_key, host (an http or https URL), timeout, device and model (an Ollama model name). Paths and endpoints (ComfyUI workflow, model paths, base URLs) are set in Preferences > Add-ons > Meshwire.

---

Configuration

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

  --host HOST   Blender addon host (default: 127.0.0.1)
  --port PORT   Blender addon port (default: find it, see below)

Which Blender the server talks to is decided in this order:

1. --port, if given.
2. The MESHWIRE_PORT environment variable, if set.
3. Discovery. Each running add-on publishes a small file in instances/ inside the Meshwire config folder (next to the token), and the server picks the most recently started Blender. It moves on to an older one only past a port that is not a Meshwire add-on holding your token. A busy or full newest Blender gives an error naming it. It looks again at every connection, so a Blender that starts or restarts later is found, and it logs the port, Blender version and .blend file it chose. Discovery runs only when --host is a loopback address.
4. Port 9876.

An explicit port is never second-guessed by discovery. With several Blenders open and no port given, the newest one wins; pass --port to talk to another.

In Blender, the Meshwire tab sets the socket port and starts or stops the server. Port 0 (the default) takes the first free port from 9876 to 9885, so a second Blender simply gets the next one. A port you set yourself is bound exactly or the start fails with a message saying why.

---

Blender versions

Meshwire supports Blender 4.2 through 5.2. Blender 4.5 LTS and 5.2 LTS are tested on every pull request. Blender 4.2, 4.3, 4.4, 5.0 and 5.1 are tested nightly on a best-effort basis.

---

Troubleshooting

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

"Python execution is off": click Allow Python in the Meshwire sidebar tab. It resets whenever Blender starts.

"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 from Get Extensions > Install from Disk.

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 (Preferences > Add-ons > Meshwire, or the RODIN_API_KEY and MESHY_API_KEY environment variables), 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

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.

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.