SketchUp MCP

SketchUp MCP is an open-source SketchUp extension + MCP server that gives AI assistants and automation clients a reliable way to explore, measure, and edit 3D scenes.

If you are building agentic design workflows, planning tools, or model-aware copilots, this project provides a practical bridge between MCP clients and real SketchUp production models.

Why people use it

SketchUp MCP is built for teams that want structured 3D workflows instead of brittle one-off scripts.

Typical usage patterns include:

• Site and model discovery through structured scene-query tools
• Option exploration and rapid 3D concept iteration
• Semantic authoring for domain elements (paths, structures, terrain-linked objects)
• Managed terrain lifecycle workflows (create, adopt, edit)
• Model measurement and validation checks in iterative design loops

What you can do with it

• Interrogate scene state with explicit inventory, targeting, and measurement tools
• Author and update semantic site elements through stable MCP contracts
• Build and edit managed terrain surfaces with create/adopt/edit flows backed by tiled heightmap state and adaptive derived SketchUp output
• Curate, discover, and instantiate staged asset exemplars as editable scene objects
• Orchestrate structured model edits (grouping, reparenting, transforms, materials)
• Integrate SketchUp into iterative, agent-assisted planning and design workflows

Who this is for

• Engineers building MCP clients for design/construction workflows
• Teams experimenting with AI-assisted 3D planning and authoring
• Contributors interested in SketchUp automation, runtime design, and tool contracts

Project status

This repository is actively developed and includes runtime code plus product/architecture documentation.

Current direction lives in:

• Platform HLD: specifications/hlds/hld-platform-architecture-and-repo-structure.md
• Domain analysis: specifications/domain-analysis.md
• Capability HLDs and tasks: specifications/hlds/ and specifications/tasks/

Documentation map

Start here, then branch by need:

1. Project orientation + setup: this README
2. MCP contract and payload details: docs/mcp-tool-reference.md
3. Contributor operating guidance: AGENTS.md
4. Architecture and roadmap context: specifications/

A dedicated docs site may be added later; currently, authoritative docs are versioned in this repository.

Quick start (local development)

Install dependencies:

bundle install

The extension loader is src/su_mcp.rb, which registers src/su_mcp/main.rb with SketchUp.

For local development, load the extension from this repository by symlinking or copying src/ into SketchUp's Plugins directory.

When loaded in SketchUp, the extension adds one Managed Terrain toolbar for managed-terrain tools. It contains Target Height Brush, Local Fairing, and Corridor Transition buttons. All three open the shared Managed Terrain panel, which keeps selected-terrain and status feedback visible while switching between tool settings. Bounded brush controls use slider plus numeric input pairs; direct numeric radius and blend values can exceed the slider's ergonomic 100m range when otherwise valid. Corridor Transition captures explicit start and end controls, supports numeric endpoint X/Y/elevation edits, includes Recapture and Sample Terrain actions for each endpoint, and exposes width plus side-blend settings before Apply. Applies route through the existing managed terrain edit command path for the current

... View full README on GitHub