MCP Server for SketchUp
Connect Claude (or any MCP-aware AI client) to SketchUp for prompt-driven 3D modeling.
Two-process bridge:
- Python MCP server (
sketchup-mcp2on PyPI) — exposes typed tools to the LLM via the Model Context Protocol.
Agenten stärken
Installation vom Herausgeber. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
Noch kein paketiertes Release in der Registry. Folgen Sie der README des Repositorys.
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenVom Herausgeber
Connect Claude (or any MCP-aware AI client) to SketchUp for prompt-driven 3D modeling.
Two-process bridge:
sketchup-mcp2 on PyPI) — exposes typed tools to the LLM via the Model Context Protocol.MCP Server for SketchUp
Either grab the latest .rbz from the Releases page or build it from source:
gem install --user-install rubyzip
(cd mcp_for_sketchup && ruby package.rb)
# → mcp_for_sketchup/mcp_for_sketchup_v<version>.rbz
In SketchUp: Window → Extension Manager → Install Extension, pick the .rbz, restart SketchUp. The plugin ships with eval_ruby — arbitrary Ruby execution inside SketchUp — enabled by default; uncheck Enable Ruby evaluation in Plugins → MCP Server → Settings... to close the gate.
Plugins → MCP Server → Start Server — by default listens on 127.0.0.1:9876.
For Claude Code / Claude Desktop, add to .mcp.json (or claude_desktop_config.json):
{
"mcpServers": {
"sketchup": {
"command": "uvx",
"args": ["sketchup-mcp2"],
"env": {
"SKETCHUP_MCP_HOST": "127.0.0.1",
"SKETCHUP_MCP_PORT": "9876",
"SKETCHUP_MCP_TIMEOUT": "60",
"SKETCHUP_MCP_LOG_LEVEL": "INFO"
}
}
}
}
That's it. Ask Claude things like "create a 1.2 × 0.8 m oak dining table" and watch it happen.
All dimensions in millimeters; angles in degrees. Every entity-returning handler also responds with bbox_mm so the LLM can re-locate entities by bounding box if their IDs go stale after destructive ops.
hello carrying client_version; the server validates against its supported range and replies with server_version + client_id. Incompatible pairs surface immediately as IncompatibleVersionError and the socket is closed.model.start_operation/commit_operation, so a single Edit → Undo rolls back the whole call.sketchup_modeling_strategy — surfaced in MCP-aware clients' slash menu; teaches the model project conventions (mm units, typed-tools-vs-eval_ruby, pitfalls like reversed Group#subtract).Plugins → MCP Server → Settings... for host / port / log level. Log level applies immediately; host/port changes prompt for a restart..mcp.json)Open Plugins → MCP Server → Settings... to change Host, Port, Log Level, the Ruby evaluation gate, and log-to-file options. Values persist in SketchUp's preferences under section MCPforSketchUp. No environment variables are read on the Ruby side.
The Ruby side logs at WARN by default, so it stays quiet in SketchUp's shared Ruby console; any line it does print is prefixed [MCPforSU] with a UTC timestamp. Enable Log to file to mirror every line to a UTF-8 log file in addition to the console (Plugins → MCP Server → Show Log opens it). The file is written append-only — there is no automatic rotation or size cap, so rotate or clean it up yourself for long-lived sessions.
eval_ruby — the arbitrary-Ruby escape hatch — is enabled by default. Uncheck Enable Ruby evaluation in the Settings dialog to close the gate; the setting persists across SketchUp restarts, and re-enabling it pops a blocking confirmation spelling out the risk (arbitrary Ruby ⇒ full filesystem / network / shell access). With the gate closed, a client's eval_ruby call comes back as a plain message telling the user how to re-open it.
Per-call review. Open gate or not, the exact Ruby a client sends stays visible in your MCP client — Claude Desktop and Claude Code display every tool call's arguments and let you approve or deny each one before it runs, so you can review each snippet case by case. (That per-call prompt is skipped only if you opt out of approvals, e.g. Claude Code's --dangerously-skip-permissions.) This review covers only calls made through that client — see Security model.
⚠ Security warning: binding the host to
0.0.0.0exposes the MCP server — includingeval_ruby, which runs arbitrary Ruby inside SketchUp — to the entire local network with no authentication. Use only on trusted networks (host → VM, isolated lab). See Security model; for multi-machine setups use the SSH tunnel described there.
The plugin's TCP socket has no authentication. Anything that can open a connection to its port can call every tool, and eval_ruby — arbitrary Ruby with full filesystem, network and shell access — is one of them for as long as Enable Ruby evaluation is on, which it is by default. That means any process on the SketchUp machine, and other machines too when Host is not a loopback address.
127.0.0.1, so only local processes can connect, and they already run with your permissions.-warehouse build (the eval-disabled variant published with 0.2.0 and 0.3.0), where eval_ruby shipped closed: with no stored preference the shipped default applies (eval_ruby is on since 0.3.1) and no confirmation appears. Open Settings once and uncheck Enable Ruby evaluation if you do not want it. An install where it was unchecked explicitly stays that way.127.0.0.1 and run this on the Windows machine:
ssh -N -R 9876:127.0.0.1:9876 user@linux-vm
The MCP server on the Linux side then connects to 127.0.0.1:9876, the default. You need the OpenSSH client on Windows (built into Windows 10/11) and sshd on the VM. The tunnel's VM end listens on the VM's loopback, so every process on the VM, under any user, reaches the plugin — eval_ruby included, while the gate is open — through it; sshd's default GatewayPorts no is what keeps the port off the VM's network.0.0.0.0 exposes the plugin to every machine that can reach the port — eval_ruby included, while Enable Ruby evaluation is on. The Settings dialog's inline warning appears only for wildcard hosts such as 0.0.0.0, not for an explicit LAN IP; the server itself logs a WARN when it binds to any non-loopback host (in SketchUp's Ruby Console, and in the log file if you enabled it).Things you can ask Claude:
eval_ruby with dovetails"For richer Ruby recipes that drive the SketchUp API directly — framed walls, gable/hip roofs, joist arrays, follow_me extrusions, world-space transforms, common pitfalls — see docs/sketchup-ruby-cookbook.md.
Working examples and load tests live in examples/:
smoke_check.py — 26-step end-to-end verification of every tool category.smoke_multi_client.py — concurrent multi-client load test.Claude (MCP client)
↕ MCP (stdio)
Python MCP server (FastMCP) src/sketchup_mcp/
↕ TCP — JSON-RPC 2.0, 4-byte big-endian length-prefix framing, 64 MiB cap
Ruby SketchUp extension (server) mcp_for_sketchup/mcp_for_sketchup/
↕ SketchUp Ruby API
Live SketchUp model
The Ruby side runs entirely on the SketchUp UI thread via UI.start_timer callbacks (SketchUp's Ruby is single-threaded — no native threads allowed). The Python side holds one persistent TCP socket per process and serialises tool-calls with an asyncio.Lock.
Source layout:
src/sketchup_mcp/{tools,connection,config,compat,errors,prompts}.pymcp_for_sketchup/mcp_for_sketchup/{core,handlers,helpers,ui}/See CLAUDE.md for the project's working notes and non-obvious constraints (unit conversions, reversed boolean semantics, framing details, etc.).
uv pip install -e .
python -m sketchup_mcp # direct
uvx sketchup-mcp2 # production-style (from PyPI)
ruby test/run_all.rb # Ruby unit tests (minitest; stdlib + rubyzip for the package test)
uv run pytest tests/ -q # Python unit tests
uv run python examples/smoke_check.py # 26-step end-to-end
uv run python examples/smoke_multi_client.py # concurrent multi-client
For a split-host setup (e.g. Linux dev box + Windows SketchUp), run the smokes on the Linux side. The file export_scene writes in step 18 of smoke_check.py then lands on the SketchUp machine, so that step only asserts that a path came back. Two ways to reach SketchUp:
127.0.0.1, so the script cannot tell that SketchUp is remote. Run SKETCHUP_MCP_SMOKE_REMOTE=1 uv run python examples/smoke_check.py; without the variable step 18 looks for the export file on the Linux machine and fails. smoke_multi_client.py needs nothing extra.SKETCHUP_MCP_HOST=<sketchup-host>. A non-loopback host is recognized as remote on its own. The plugin has to listen on that address, with the risks described in the Security model.SketchUp not running or extension not started: ...The Python MCP server connected to the configured host/port but found nothing listening. Either:
Plugins → MCP Server → Start Server.The Python server stays alive after this error; the next tool-call retries the connect.
IncompatibleVersionErrorOne side is older than the other accepts. The message names the outdated side and the minimum version it needs:
uvx sketchup-mcp2@latest once (or uv pip install -U sketchup-mcp2 for a pip install), then restart your MCP client. A plain uvx sketchup-mcp2 keeps running its cached version..rbz from GitHub Releases.Each side declares only the oldest counterpart it works with, so being newer never fails the handshake. Releases up to 0.3.1 are the exception: they accept only a counterpart of their own version, so moving past 0.3.1 means upgrading both once. The floors live in src/sketchup_mcp/compat.py (MIN_RUBY) and mcp_for_sketchup/mcp_for_sketchup/core/compat.rb (MIN_PYTHON).
Bump SKETCHUP_MCP_TIMEOUT in your .mcp.json env block. Default is 60 seconds. Keep it well above 30 s: a chamfer or fillet call starts no new cut after 30 s inside SketchUp and then rolls back, and a client that gives up sooner can walk away from an edit that still commits.
SketchUp does not learn that the client gave up. After a timed-out call that changes the model, check the model with get_component_info or list_components before retrying — a blind retry can apply the edit twice (a double chamfer). The error message says the same. Read-only calls are safe to repeat.
Frame-decoding is capped at 50 reads × 64 KiB per client per tick (~3.2 MB) to keep the UI responsive, but a very large eval_ruby body or a runaway loop inside it will still freeze SketchUp until it returns. Break the work into smaller calls if you can.
connection timed out after 30000ms at startupIf the client can't connect but SketchUp itself is reachable (e.g. telnet <host> 9876 succeeds), the bottleneck is the Python server's own startup, not the link to SketchUp.
The usual culprit is running the server from a source checkout whose virtual environment lives on a slow filesystem — VMware Shared Folders (vmhgfs-fuse), VirtualBox shared folders, NFS/CIFS network drives, or WSL's /mnt/.... Python touches hundreds of small files at startup, and importing the FastMCP dependency stack from such a filesystem can take 30 s+ — past the client's init timeout. (A quick check: time uv run python -c "import sketchup_mcp.app" — if that takes tens of seconds, the filesystem is the problem.)
Keep the virtualenv on a local disk. With uv, point it there via UV_PROJECT_ENVIRONMENT in the server's .mcp.json env block — the project source can stay on the shared folder (it's small, and editable installs pick up changes live); only the dependency-heavy venv needs to be local:
"sketchup": {
"command": "uv",
"args": ["run", "--directory", "/path/to/sketchup-mcp2", "python", "-m", "sketchup_mcp"],
"env": {
"UV_PROJECT_ENVIRONMENT": "/home/you/.venvs/sketchup-mcp2",
"SKETCHUP_MCP_HOST": "127.0.0.1"
}
}
The uvx sketchup-mcp2 setup shown earlier isn't affected — uvx already keeps its environment under uv's local cache.
Why is the venv on a shared folder at all? This bridge is typically run in an isolated VM setup — both Claude Code launched with
--dangerously-skip-permissionsandeval_ruby(arbitrary Ruby, full filesystem/shell access) enabled are risky enough to want a disposable VM. Typical layout: a Linux VM (Claude Code + MCP server) ↔ a Windows VM (SketchUp) connected through the SSH tunnel described in Security model, project on a host-shared folder — which is exactly why theUV_PROJECT_ENVIRONMENTnote above matters.
MIT — see LICENSE.
hello handshake, MCP prompt, viewport screenshot, settings dialog, and full unit-test coverage on both Ruby and Python sides.sketchup-mcp2; the upstream package is sketchup-mcp.Pull requests welcome. Before opening one, please run both test suites (ruby test/run_all.rb and uv run pytest tests/) and — if you've touched anything in the IO path — the live smokes against a running SketchUp.
MCP Server for SketchUp
Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Sketchup Mcp2 läuft lokal über stdio.
Zuletzt geprüft: 2026-11-13. MCP Server for SketchUp