sketchup-mcp — Claude & ChatGPT ↔ SketchUp

MCP server and SketchUp extension that let Claude (Desktop, Code, claude.ai) and ChatGPT (developer-mode connectors) read and drive Trimble SketchUp: modelling, massing and GFA/FAR studies, architectural elements, scenes and sun studies, model audits, schedules, import/export and Ruby. It follows the same architecture as revit-mcp: a TypeScript MCP server with auto-registered tools, a team rules/guides knowledge base with a rules gate, local SQLite snapshots and GitHub releases. The SketchUp side is the companion extension.

Claude Desktop / ChatGPT Desktop / Codex ──stdio──┐
                                                  ├─▶ sketchup-mcp server (Node.js, src/ → build/index.js)
claude.ai / ChatGPT web ──HTTPS (tunnel)──────────┘        │  TCP 127.0.0.1:9876
                                               ▼
                                   SketchUp ▸ Extensions ▸ SketchUp MCP-APG (sketchup-extension/ → .rbz)
                                   └─ Connect AI: installs the server + Node.js, configures the local
                                      desktop clients, and can run the web connector (same .rbz)

Version 2.0 is a rebuild of the original Python sketchup-mcp 0.1.x (kept in legacy/). The original boolean, chamfer/fillet and joinery commands called SketchUp methods that do not exist and could not work; they were rewritten on SketchUp's native solid tools. 74 extension commands / 82 MCP tools.

What it can do

Full reference: docs/TOOLS.md (generated from the code).

Related MCP server: sketchup-mcp2

Quick start

One plugin, no terminal. Download sketchup-mcp-extension-vX.Y.Z.rbz from Releases (Windows without internet access: sketchup-mcp-extension-win-full-vX.Y.Z.rbz, which also carries Node.js), then in SketchUp Extensions ▸ Extension Manager ▸ Install Extension. The Connect AI window opens by itself and starts first-run setup automatically (later: Extensions ▸ SketchUp MCP-APG ▸ Connect AI… or the toolbar):

Settings in the same window: units, tool set, your name, connector port, a fixed public URL (ngrok / named tunnel) instead of the quick tunnel, start the connector with SketchUp, use your own Node.js. SketchUp 2021 or newer (desktop); solid tools, openings, rounding and joinery need SketchUp Pro.

Claude Desktop / Claude Code with Node.js 22.13+ and git:

{
  "mcpServers": {
    "sketchup-mcp": {
      "command": "npx",
      "args": ["-y", "github:OmarEAbdelaal/sketchup-mcp"],
      "env": { "SKETCHUP_MCP_UNITS": "mm", "SKETCHUP_MCP_USER_NAME": "Your Name" }
    }
  }
}

Claude Code: claude mcp add sketchup-mcp -e SKETCHUP_MCP_UNITS=mm -- npx -y github:OmarEAbdelaal/sketchup-mcp. Or unzip sketchup-mcp-server-vX.Y.Z.zip (Windows zip contains runtime/node.exe) and point command at runtime\node.exe build\index.js. ChatGPT / claude.ai from a terminal:

npx -y github:OmarEAbdelaal/sketchup-mcp --http --tunnel     # downloads cloudflared if missing
#  PUBLIC MCP URL: https://<random>.trycloudflare.com/mcp/<token>

Step-by-step guide for every client, daily use and troubleshooting: SKETCHUP_MCP.md.

Units

All tool inputs/outputs use SKETCHUP_MCP_UNITS (default mm; also cm, m, in, ft). Areas are reported in m² (ft² for imperial) and volumes in m³ (ft³). Inside Ruby (send_code_to_sketchup) SketchUp works in inches — write 3.m / 1000.mm; the linter warns on bare numbers.

Team rules (knowledge base)

Same system as revit-mcp. Every client receives short instructions at connection; before the first change in a task the AI must call get_sketchup_rules(task) (model-changing tools are refused until then) and gets only the rules that apply. Ruby sent to SketchUp is checked first (own undo operations, UI dialogs, shell commands and file deletion are blocked; inch mistakes and explode get warnings). Everything is logged in rules-audit.jsonl.

• knowledge/db/rules.json — 48 rules + 6 rejected approaches (starter set — review and adapt).

• knowledge/guides/*.md — how-to guides: Ruby runner, modelling hygiene, massing & areas, documentation & sun studies, architecture elements, solids & joinery, import/export, setup.

• Rules and guides are read live from main (6 h cache, offline fallback), so edits need no release. Private company/project rules: SKETCHUP_MCP_PROJECT_RULES. Details: knowledge/README.md.

Configuration

Repository layout

src/                       MCP server (TypeScript, Node 22.13+)
  index.ts                 entry: stdio (default) | --http [--tunnel] | --print-config
  server.ts                creates the McpServer (instructions, tools, prompts, resources)
  http.ts                  Streamable HTTP + SSE transport, token auth, cloudflared tunnel, managed mode
                           (--status-file / --log-file / --parent-pid / POST /shutdown) for the extension
  tools/*.ts               tool modules, auto-registered (tools/_define.ts = shared tool wrapper + gate)
  kb/                      rules, guides, rules gate + Ruby lint, prompts/resources
  database/                SQLite snapshots (node:sqlite)
  utils/                   config, TCP client to SketchUp, cloudflared finder/installer
sketchup-extension/        SketchUp extension → .rbz
  su_mcp.rb                loader
  su_mcp/server.rb         TCP JSON-RPC service (main-thread polling, newline framing)
  su_mcp/commands/*.rb     74 commands (core, query, geometry, edit, solids, components, materials,
                           organize, view, analysis, architecture, io, joinery, ruby)
  su_mcp/setup/            Connect AI: installer (server + Node.js), desktop client config, connector,
                           hidden process runner, dialog (ui/connect.html)
knowledge/                 rules database, guides, generated INSTRUCTIONS/REJECTED/PROPOSED
scripts/                   kb-build, package (rbz with server inside, full Windows rbz, server zip),
                           gen-tools-doc, test/ (stub, e2e, setup_test.rb)
docs/TOOLS.md              generated tool reference
examples/                  client configs and example prompts
legacy/                    the original Python sketchup-mcp 0.1.17 (superseded)

Development

npm install            # also builds (prepare)
npm run build          # tsc + knowledge build
npm test               # e2e: SketchUp API stub (Ruby) ⇄ server ⇄ MCP client over stdio and HTTP
npm run docs           # regenerate docs/TOOLS.md
npm run package        # dist/sketchup-mcp-extension-vX.rbz (server inside) + dist/sketchup-mcp-server-vX.zip
node scripts/package.mjs --node win-x64   # + win-full .rbz and server zip with checksum-verified node.exe
ruby scripts/test/setup_test.rb dist/sketchup-mcp-server-vX.zip   # Connect AI: installer, Claude config, connector

npm test exercises the full chain against scripts/test/sketchup_stub.rb, a minimal stand-in for the SketchUp API (connection, tool listing, rules gate, lint, search/fetch, HTTP auth). Geometry commands can only be verified inside SketchUp — see the checklist in CHANGELOG.md.

Add a tool

1. SketchUp side: add a Registry.command('name', 'summary') { |p| … } block to a file in sketchup-extension/su_mcp/commands/ (use Util.len/pt for inputs, Util.out/pt_out for outputs and Util.operation for one undo step).

2. Server side: add a defineTool(server, { name, title, group, description, schema, writes }) entry to a module in src/tools/ (files are registered automatically).

3. npm run build && npm test && npm run docs, then release.

Release

npm version minor && git push && git push --tags

The Build workflow runs on every push (artifacts) and on a v* tag publishes on a GitHub Release: sketchup-mcp-extension-<tag>.rbz (extension + server), sketchup-mcp-extension-win-full-<tag>.rbz (+ Node.js for Windows) and sketchup-mcp-server-<tag>.zip (with runtime/node.exe). It can also be dispatched manually with release_tag.

Credits & license

MIT. Original sketchup-mcp (Python, 2024, inspired by blender-mcp); 2.0 rebuild, extension, tools, knowledge base and revit-mcp alignment by Omar Elsayed.