Skip to main content
Glama
sketchup-headless-mcp

sketchup-headless-mcp

by JakeBilu

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.

Related MCP server: Ringo SketchUp MCP

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

pip install -e .

Run the CLI Headless Runner

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

Configure as an MCP Server

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

License

MIT — see LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      10
      13
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      Enables MCP clients to inspect and modify SketchUp models through a local authenticated bridge, covering entity creation and editing, geometry, materials, tags, cameras, scenes, transactions, snapshots, and file or view export. It also offers an optional full SketchUp Ruby API execution channel and batch operations for furniture, architectural, and analysis tasks.
      37
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI clients to drive SketchUp Pro 2026 on a Windows host, including from WSL, by executing arbitrary Ruby in the active model, reading scene and selection details, and capturing viewport screenshots. It talks to a loopback TCP bridge inside SketchUp using a connect-per-command protocol for reliable, desync-free control.
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to automate 2D architectural drafting and CAD file management, including DXF/DWG parsing, SVG/PNG/PDF rendering, wall extrusion to 3D STL meshes, room and beam analysis, block/script library access, and persistent depot storage via a REST API and MCP tools.
      18
      MIT