Skip to content
BlenderMCP

Add your own tools

The Chat tab’s assistant can use tools from other MCP servers you add, alongside its Blender tools. Add a PDF server and it can read a spec sheet; add a CAD server and it can read a DXF floor plan and hand the walls to extrude_polygons. This works with every chat backend: the shared GPU gateway, your Claude key, or an OpenAI-compatible endpoint.

Servers you add run on your computer, started by the add-on, even when you give an HTTPS address. They can reach your files, and their credentials never leave your machine. The BlenderMCP server never starts or connects to them itself.

Add a server

Section titled “Add a server”

Edit › Preferences › Add-ons › Blender MCP › Tool servers › Add, then fill in:

| Field | Example | Notes | |---|---|---| | Name | pdf | Short, lowercase letters, digits and -. Shown on tool steps and used in tool names (pdf__read_text). | | Start with | uvx mcp-pdf | A command for a local server, or an https:// address for a remote one. | | Environment | PDF_ROOT=/home/me/docs | One KEY=value per line, passed to a local server. | | Token | ${MY_SERVER_TOKEN} | For remote servers. Write ${VAR} to read it from an environment variable, which keeps it out of Blender’s preferences file. | | Trusted | off | Off: each call asks Allow/Deny in the Chat tab. On: calls run without asking. | | Timeout | 60 | Seconds per call. |

Press Test to start it and list its tools. Enabled servers start in the background when the add-on connects, so a slow first install (a FreeCAD-based server, say) doesn’t hold up chat.

Wire contract

Section titled “Wire contract”

The add-on reports its tools: blender_report_user_tools (add-on role only)

Section titled “The add-on reports its tools: blender_report_user_tools (add-on role only)”
blender_report_user_tools(tools: list[{server, name, description, input_schema, trusted, timeout_s}])
  • Replaces the full set for the calling Blender; an empty list clears it. Sent after registration and whenever a server’s tools change.
  • timeout_s is the server’s Timeout setting in seconds: an integer from 1 to 600, 60 when missing.
  • Limits: at most 80 tools, description cut to 1,000 characters, input_schema at most 8 KB of JSON each; oversize entries are dropped and listed.
  • Returns {"status": "ok", "accepted": 12, "dropped": [{"server", "name", "reason"}]}. A reason is one of too_many_tools, invalid_server (not 1 to 64 of A-Z a-z 0-9 _ -), invalid_name (empty, over 128 characters, or containing whitespace), duplicate, invalid_schema (not a JSON object schema), schema_too_large or invalid_timeout (not an integer from 1 to 600).
  • The set lives in server memory for that Blender’s session; the add-on re-reports after reconnecting.

Chat names

Section titled “Chat names”

The model sees each reported tool as {server}__{name}, reduced to A-Z a-z 0-9 _ - and 64 characters. A name that collides with a Blender tool or another reported tool gets _2, _3, … appended; it never replaces a Blender tool. Blender tools come first in the catalog, and the total offered to the model is capped (40 by default, CHAT_MAX_TOOLS).

The server calls a tool: user_tool_call command (to the calling Blender only)

Section titled “The server calls a tool: user_tool_call command (to the calling Blender only)”

Dispatched like any Blender command, and only to the Blender whose add-on started the chat turn:

{"command": "user_tool_call", "params": {"server": "pdf", "tool": "read_text", "arguments": {"path": "spec.pdf"}, "timeout_s": 60}}
  • timeout_s is the value the add-on reported for that tool. The add-on clamps it to the server’s Timeout in its own preferences, and the server waits timeout_s plus 15 seconds for the reply, so the add-on’s own timeout answer arrives first.
  • The server refuses to send user_tool_call for anyone else: blender_submit and bus_send_message answer chat_only_command, so MCP clients never reach these tools.
  • The add-on looks server up in its own preferences. A name it doesn’t have is refused: commands and addresses only ever come from the user’s preferences, never from the server.
  • The call runs off Blender’s main thread. The result is {"ok": true, "text": "...", "truncated": false}; text content is joined, images are replaced by a short note, and text is cut to 20,000 characters.
  • A timeout or a crashed server returns {"ok": false, "text": "<reason>"}; the add-on restarts a crashed server on its next call.

Transcript

Section titled “Transcript”

Tool progress events for these tools carry the chat name plus "server": "pdf", and the Chat tab shows them as pdf · read_text 1.20 s. Untrusted servers ask for approval with the usual BlenderMCP approval: elicitation, previewing the arguments.