sketchup-mcp-bridge
Drives SketchUp Pro 2026 by executing arbitrary Ruby in the active model, retrieving scene information and current selection, and capturing rendered screenshots.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sketchup-mcp-bridge make a 3m cube at the origin and screenshot the viewport"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
sketchup-mcp-bridge
A robust Model Context Protocol (MCP) server that lets an AI client (e.g. Claude Code) drive SketchUp Pro 2026 on a Windows host — including from WSL.
Verified working on SketchUp engine 26.1.256. MIT license.
Why This Exists
The most popular existing tool (mhyrr/sketchup-mcp) has two failure modes this project fixes by design:
Persistent-socket desync — the original client held one socket open and sent a
pingwithout reading its reply. SketchUp responded "Method not found", which was then mis-read as the response to the next command, so every other call failed with "Communication error with Sketchup: Method not found". Fix: connect-per-command — a fresh TCP connection is opened for each MCP tool call and closed immediately after the response.Write-hang — the original Ruby server mutated the model inside the timer loop. A mutation that raised inside an open
start_operationleft a dangling transaction and hung the entire server (subsequent writes timed out). Fix: everyevalis wrapped instart_operation/commit_operationwith a guaranteedabort_operationon error; the timer loop is "immortal" — no exception can escape it.
Also note: install from source / git, not a stale PyPI build. Some published builds crash with FastMCP.__init__() got an unexpected keyword argument 'description'; this repo uses instructions= (the current FastMCP API).
Related MCP server: SketchUp MCP Server
Architecture
Claude Code (WSL / any host)
│ MCP stdio transport
▼
Python MCP server (FastMCP, run via uvx)
│ TCP connect-per-command → 127.0.0.1:9876
▼
Ruby TCP server (UI.start_timer loop inside SketchUp)
│
▼
SketchUp Pro 2026 modelTwo components:
Ruby extension — runs a TCP server on
127.0.0.1:9876inside SketchUp. Built around aUI.start_timeraccept loop on the main thread so Ruby API calls are safe. One request per connection.Python MCP server — a FastMCP server (
uvx-installable) that acts as a connect-per-command TCP client; each tool call opens, uses, and closes one TCP connection.
Wire Protocol
Each exchange is a single JSON line terminated by \n.
Request:
{"id": 1, "cmd": "eval", "args": {"code": "Sketchup.version"}}Success response:
{"id": 1, "ok": true, "result": "26.1.256"}Error response:
{"id": 1, "ok": false, "error": "NameError: undefined local variable ..."}The Ruby server closes the socket after writing the response. The Python client opens a fresh connection for every command. This is deliberate — it eliminates all desync issues.
Tools
Tool | Arguments | Description |
|
| Execute arbitrary Ruby in the active model; returns |
| — | Model title, entity count, active length unit, model bounds, selection size |
| — | Selected entities — entityID, typename, bounding box |
| — | Renders the current view to a PNG on the host and returns it as an image |
Installation
1. SketchUp Extension (.rbz)
Get the extension — either download the prebuilt .rbz (easiest):
https://github.com/Shattenjagger/sketchup-mcp-bridge/releases/latest/download/su_mcp_bridge.rbzThis asset is rebuilt automatically on every push to master.
…or build it from source:
python3 scripts/build_rbz.py
# → dist/su_mcp_bridge.rbz (plain zip, no `zip` binary required)Install in SketchUp:
Window → Extension Manager → Install Extension
Select
dist/su_mcp_bridge.rbzAccept the unsigned-extension prompt
Restart SketchUp
Start the server each session:
Extensions → SketchUp MCP Bridge → Start Server
The Ruby Console will print:
[SUMCPBridge] listening on 127.0.0.1:9876There is no autostart — you need to start the server at the beginning of each SketchUp session.
2. Python MCP Server (via uvx)
Register with Claude Code (user scope):
claude mcp add sketchup --scope user -- \
uvx --from git+https://github.com/Shattenjagger/sketchup-mcp-bridge \
sketchup-mcp-bridge --port 9876For a local checkout, substitute --from /path/to/local/clone.
Then restart Claude Code so it picks up the new MCP tools.
Configuration flags and environment variables:
Flag | Env var | Default | Description |
|
|
| Host where SketchUp is running |
|
|
| TCP port the Ruby server listens on |
|
| none (required for | WSL path to a host-side temp dir (e.g. |
WSL + Windows Networking
If Claude Code runs in WSL and SketchUp on the Windows host, the Ruby extension binds 127.0.0.1 on the host — which is not reachable from WSL under default NAT networking.
Enable mirrored networking (requires Windows 11 22H2+):
Add the following to C:\Users\<you>\.wslconfig:
[wsl2]
networkingMode=mirroredThen shut down WSL and reopen it:
wsl --shutdownAfter that, the host's localhost:9876 is reachable from WSL without any port forwarding.
Screenshot directory: there is no default. You must set --screenshot-dir (or SKETCHUP_MCP_SCREENSHOT_DIR) to a WSL path that maps to a Windows temp directory, for example:
--screenshot-dir /mnt/c/Users/<you>/AppData/Local/Temp(or any WSL-visible directory on the Windows host). The screenshot tool raises a clear error if this is not configured.
Security
eval_ruby executes arbitrary Ruby in your SketchUp process with full SketchUp API access — there is no sandbox. The Ruby server binds loopback only (127.0.0.1) and is intended as a local, single-user developer tool on your own machine.
Do not expose port 9876 to a network. Do not use this in a shared or multi-user environment.
Development
Python environment is managed with uv.
# Run tests
uv run pytest # 14 tests
# Rebuild the extension after Ruby changes
python3 scripts/build_rbz.py
# Then reinstall dist/su_mcp_bridge.rbz in SketchUp and restart SketchUpLicense
MIT — see LICENSE.
Available Tools
4 toolseval_rubyA
Execute arbitrary Ruby in the active SketchUp model and return result.to_s.
Inputs: code (required). Returns: result
get_scene_infoB
Return model title, entity count, active units, bounds, and selection size.
Inputs: no named parameters. Returns: result
get_selectionA
Return the currently selected entities (entityID, typename, bbox).
Inputs: no named parameters. Returns: result
screenshotA
Capture the current SketchUp view and return it as an image.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool serves a clearly distinct purpose: eval_ruby executes arbitrary code, get_scene_info returns model metadata, get_selection returns selected entities, and screenshot captures the viewport. There is no overlap or ambiguity in when to use each tool.
Three tools use a verb_noun pattern (eval_ruby, get_scene_info, get_selection), but 'screenshot' is a single noun-verb hybrid that breaks the pattern slightly. The set is still mostly predictable and readable.
Four tools is a lean, well-scoped set for a bridge server. Each tool earns its place: one general execution tool plus three focused observation helpers.
The eval_ruby escape hatch allows arbitrary model modifications, so most SketchUp operations are reachable. However, the lack of structured write/update/delete tools for specific entity types means agents must rely on raw Ruby rather than dedicated operations.
Maintenance
Related MCP Connectors
Connect your AI assistant to Blender for 3D modeling, Geometry Nodes, materials, lighting, animation, rendering and export. Inspect real scenes and viewport images, refine the result and restore checkpoints. OAuth connects your chat to Blender Bridge Desktop on an online Windows 10/11 x64 computer running Blender 4.2+. The chat can run on another device. Requires an active Blender Bridge account; 7-day trial available. AI model access is separate.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Remote Desktop Commander: use files, terminal and processes on your own computers from any AI app.
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables direct interaction and control of SketchUp through Claude AI using the Model Context Protocol and a TCP socket connection. It allows for prompt-assisted 3D modeling, component manipulation, and the execution of arbitrary Ruby code within the SketchUp environment.101MIT
- AlicenseAqualityDmaintenanceControls SketchUp via AI assistants, enabling 3D model creation programmatically through the Model Context Protocol.2115MIT
- AlicenseBqualityCmaintenanceEnables controlling SketchUp from MCP-compatible clients via a stdio Python server that bridges to a Ruby plugin, supporting component operations, material assignment, scene export, arbitrary Ruby evaluation, and wood joinery tools.1013MIT
- AlicenseAqualityCmaintenanceConnects MCP-aware AI clients to a live SketchUp session so models can be built and edited through natural-language prompts. Exposes typed tools for geometry creation, materials, booleans, edge chamfers/fillets, joinery, scene export, model introspection, viewport screenshots, and an optional arbitrary-Ruby escape hatch.24MIT