BlenderMCP for Windsurf: Setup & Config

What you can do with BlenderMCP in Windsurf

Combine prompt-driven Blender editing with scene inspection and optional external 3D asset pipelines.

• Inspect a Blender scene and individual object properties.
• Create geometry and modify materials from an assistant conversation.
• Capture viewport images to inform scene iteration.

Before you start: BlenderMCP in Windsurf

• Blender 3.0 or later
• Python 3.10 or later
• uv with uvx available for this setup
• The repository's addon.py installed and enabled in Blender
• An MCP-compatible client

Configure the MCP client, install the addon, and connect it through Blender's BlenderMCP sidebar. Run only one server instance across clients. Optional BLENDER_HOST and BLENDER_PORT customize the socket connection; DISABLE_TELEMETRY=true disables telemetry.

BlenderMCP Windsurf configuration

1. Choose Windsurf configuration scope

   For BlenderMCP, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add BlenderMCP to Windsurf

   Use the blender-mcp entry below in mcpServers. Keep BlenderMCP's documented stdio connection fields and your other Windsurf entries.

3. Check BlenderMCP in Windsurf

   BlenderMCP: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "blender-mcp": {
      "command": "uvx",
      "args": [
        "blender-mcp"
      ],
      "env": {}
    }
  }
}

BlenderMCP tools available to Windsurf

BlenderMCP's stored tool list documents 17 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

get_scene_info

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for get_scene_info.

Inspect the current Blender scene.

get_object_info

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for get_object_info.

Read details for a named scene object.

get_viewport_screenshot

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for get_viewport_screenshot.

execute_blender_code

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for execute_blender_code.

get_polyhaven_categories

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for get_polyhaven_categories.

search_polyhaven_assets

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for search_polyhaven_assets.

download_polyhaven_asset

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for download_polyhaven_asset.

Download and import a selected Poly Haven asset.

set_texture

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for set_texture.

Apply a downloaded Poly Haven texture to a scene object.

get_polyhaven_status

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for get_polyhaven_status.

Check whether Poly Haven integration is enabled.

get_hyper3d_status

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for get_hyper3d_status.

get_sketchfab_status

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for get_sketchfab_status.

search_sketchfab_models

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for search_sketchfab_models.

download_sketchfab_model

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for download_sketchfab_model.

generate_hyper3d_model_via_text

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for generate_hyper3d_model_via_text.

Generate a textured 3D asset from a description through Hyper3D and import it.

generate_hyper3d_model_via_images

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for generate_hyper3d_model_via_images.

Generate and import a Hyper3D asset using reference images.

poll_rodin_job_status

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for poll_rodin_job_status.

Check progress of a Hyper3D Rodin generation task.

import_generated_asset

After refreshing BlenderMCP in Windsurf settings, check Cascade's tool list for import_generated_asset.

Import a completed Hyper3D Rodin generation result into the scene.

BlenderMCP: full stored tool descriptions

Troubleshooting BlenderMCP in Windsurf

• Check uvx blender-mcp (from uv, for Python tools) on the machine running Windsurf's MCP integration for BlenderMCP; refresh MCP and inspect Cascade's tools.
• BlenderMCP uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires Blender, an enabled addon, and a separate MCP server connection.
• Known limitation: Arbitrary Python execution can be dangerous and warrants saving work first.
• Known limitation: Complex operations may need to be split into smaller steps.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions