# 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](https://github.com/OmarEAbdelaal/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/`](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

| Area | Tools (all lengths in mm by default) |
|---|---|
| Connection & files | `say_hello`, `get_model_info`, `undo` / `redo`, `save_model`, `open_model`, `new_model`, `set_model_units`, `list_commands`, `use_command` |
| Query | `get_entities`, `get_entity_info`, `get_selection`, `set_selection`, `find_entities` |
| Modelling | `create_primitive` (box, cylinder, tube, cone, pyramid, wedge, prism, sphere, hemisphere, torus), `create_face` (outline + holes + extrusion), `draw_lines`, `draw_curve` (circle, arc, polygon, rectangle, bezier), `push_pull`, `follow_me`, `revolve`, `offset_face`, `add_text` (labels / 3D text), `add_dimension`, `add_guide`, `add_section_plane` |
| Editing & data | `transform_entities` (move / rotate / scale / mirror), `copy_array` (linear, grid, polar, points), `align_distribute`, `delete_entities`, `group_entities`, `explode_entity`, `set_entity_properties`, `set_attributes` / `get_attributes` (incl. dynamic components), `soften_edges` |
| Solids | `solid_operation` (union, subtract, intersect, trim, split, outer shell), `intersect_faces`, `round_edges` (chamfer / fillet) |
| Components & materials | `list_definitions`, `place_component` (by name or .skp, many positions), `manage_components`, `purge_unused`, `list_materials`, `create_material` (colour, opacity, texture), `apply_material`, `color_by` (zoning / use diagrams with legend) |
| Tags & scenes | `manage_tags` (create, colour, line style, folders, isolate, assign…), `manage_scenes` |
| Views & images | `set_camera` (plan, elevations, iso, aerial, eye level), `set_view_style`, `set_sun_and_location`, **`capture_view`** (returns the image so the AI can *see* the model), **`shadow_study`** |
| Architecture | **`create_massing`** (levels, floor heights, uses, setbacks), `create_wall`, `create_opening`, `create_slab`, `create_stairs` (riser/going computed + flags), `create_roof` (gable, hip, shed, pyramid, flat), `create_grid`, `place_columns`, `create_terrain` (height grid or survey points) |
| Analysis | **`massing_report`** (GFA per level, GFA by use, FAR, coverage, facade/roof area), **`model_audit`** (health score), `generate_schedule` (components, groups, materials, tags, cut list → CSV), `detect_clashes`, `measure` |
| Import / export | `export_model` (skp, ifc, dwg, dxf, fbx, obj, dae, stl, kmz, pdf, png…), `import_file` (dwg, ifc, 3ds, obj, skp…) |
| Joinery | `create_finger_joint`, `create_dovetail`, `create_mortise_tenon`, + cut lists |
| Ruby | `send_code_to_sketchup` (one undo step, output captured, linted before it runs) |
| Team knowledge | `get_sketchup_rules`, `get_sketchup_guide`, `propose_sketchup_rule`; prompts `sketchup_rules`, `massing_study`, `model_health_check`, `presentation_scenes` |
| Design options | `store_model_snapshot`, `query_stored_data` (compare GFA/FAR between options) |
| ChatGPT | `search`, `fetch` (model objects, scenes, rules and guides) |

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

## Quick start

**One plugin, no terminal.** Download **`sketchup-mcp-extension-vX.Y.Z.rbz`** from
[Releases](https://github.com/OmarEAbdelaal/sketchup-mcp/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):

| Step | What happens |
|---|---|
| **1 · Automatic first run** | Detects the OS paths, SketchUp units, account name and active bridge port; installs a private Node.js (downloaded from nodejs.org, SHA-256 checked) and the bundled MCP server for this user. **Set up everything** retries it if needed. |
| **2 · Claude Desktop** | Writes the `sketchup-mcp` entry into `claude_desktop_config.json` (other servers kept, original backed up; Microsoft Store build included). Restart Claude and the SketchUp tools are there. Claude Code: copy the ready-made `claude mcp add …` line. |
| **3 · ChatGPT Desktop / Codex** | Writes an absolute, machine-specific local MCP entry into `~/.codex/config.toml` (other settings and servers preserved; original backed up). Restart the app and use a local chat—no tunnel or pasted URL. |
| **4 · ChatGPT / claude.ai web** | *Start connector* runs HTTP mode through a Cloudflare quick tunnel and shows the URL to approve once in ChatGPT (*Developer mode ▸ Create*) or claude.ai (*Add custom connector*). Web clients require this explicit trust step. |

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.

<details><summary>Manual setup (developers, other MCP clients)</summary>

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

```json
{
  "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:

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

Step-by-step guide for every client, daily use and troubleshooting: **[SKETCHUP_MCP.md](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](knowledge/README.md).

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `SKETCHUP_MCP_UNITS` | `mm` | Units of every length (mm, cm, m, in, ft) |
| `SKETCHUP_MCP_HOST` / `SKETCHUP_MCP_PORT` | `127.0.0.1` / `9876` | Where the extension listens |
| `SKETCHUP_MCP_TIMEOUT_MS` | `180000` | Per-command timeout |
| `SKETCHUP_MCP_TOOLSETS` | `all` | Load fewer tools: e.g. `core,query,modeling,edit,view,architecture,analysis` or `all,-joinery,-code` |
| `SKETCHUP_MCP_HTTP_PORT` / `_HTTP_HOST` | `3333` / `127.0.0.1` | HTTP mode |
| `SKETCHUP_MCP_TOKEN` | generated, saved in the data folder | HTTP secret |
| `SKETCHUP_MCP_USER_NAME` | OS login | Name stored with proposals / audit log |
| `SKETCHUP_MCP_RULES_GATE` / `_RULES_GATE_MINUTES` | `on` / `120` | Rules gate |
| `SKETCHUP_MCP_PROJECT_RULES` | — | `;`-separated private rule files/folders |
| `SKETCHUP_MCP_KNOWLEDGE_URL` / `_GUIDES_URL` / `_KNOWLEDGE_OFFLINE` | GitHub `main` | Knowledge source |
| `SKETCHUP_MCP_DATA_DIR` | `%LOCALAPPDATA%\SketchUpMCP\data` or `~/.sketchup-mcp` | SQLite, caches, audit log, token |

## 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

```bash
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](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

```bash
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](https://github.com/ahujasid/blender-mcp));
2.0 rebuild, extension, tools, knowledge base and revit-mcp alignment by Omar Elsayed.