Skip to main content
Glama
sketchup-headless-mcp

sketchup-headless-mcp

by JakeBilu
README.md
# sketchup-headless-mcp

Headless **SketchUp 2026** Ruby automation runner, **FastMCP** server, and deterministic parametric Ruby CAD/BIM/millwork/lighting libraries (`SketchUpMCPArch`, `SketchUpMCPCabinetry`, `SketchUpMCPFinishLighting`).

## Why?

Automating SketchUp via `-RubyStartup` typically fails in headless agent workflows due to:
1. Interactive welcome modals when launched without a seed `.skp` file.
2. Lingering background SketchUp processes blocking subsequent runs.
3. Non-manifold solids, overlapping bounding boxes, or missing 2D orthographic CAD plan/RCP symbols.

`sketchup-headless-mcp` pairs a clean process-managed Python runner and MCP server with production-tested Ruby geometry builders designed for zero-overlap manifold solids and dual 3D + 2D architectural output.

## Features

- **Headless Runner (`runner.py`)**: Launches SketchUp with a clean blank `assets/startup_seed.skp`, injects `SKETCHUP_MCP_LIB_DIR`, polls for the output JSON manifest, and tears down cleanly on completion or timeout.
- **FastMCP Server (`server.py`)**: Exposes `get_environment_status`, `list_ruby_libraries`, `run_sketchup_ruby`, and `build_parametric_demo`.
- **Parametric Ruby Libraries (`lib/`)**:
  - `SketchUpMCPArch` (`lib/sketchup_arch_lib.rb`): Calibrated raster underlays, swing/sliding doors, cut-plane-safe windows, straight stairs with diagonal break symbols, 2D furniture CAD projections, and LayOut hybrid viewports.
  - `SketchUpMCPCabinetry` (`lib/sketchup_cabinetry_lib.rb`): OpenCutList-aligned local-axis manifold panels, recessed plinths, multi-bay carcasses, 2 mm reveal swing/aluminum-glass doors, pelmets, wall scribes, curved end units, and full wardrobe/kitchen assemblies.
  - `SketchUpMCPFinishLighting` (`lib/sketchup_finish_lighting_lib.rb`): Anti-glare L-box cove ceilings, aluminum LED profiles, curtain pelmets, downlight grids, anti-sliver floor tile setout planner, and recursive AABB overlap + manifold QA auditing.

## Quickstart

```bash
pip install -e .
```

### Run the CLI Headless Runner

```bash
sketchup-headless-run \
  --rb examples/demo_room.rb \
  --manifest out/demo_manifest.json \
  --probe-out out/demo_manifest.json
```

### Configure as an MCP Server

```json
{
  "mcpServers": {
    "sketchup-headless": {
      "command": "sketchup-headless-mcp",
      "env": {
        "SKETCHUP_EXE": "C:\\Program Files\\SketchUp\\SketchUp 2026\\SketchUp\\SketchUp.exe"
      }
    }
  }
}
```

## License

MIT — see [LICENSE](LICENSE).