# mhyrr/sketchup-mcp architecture

> Architecture diagram of the GitHub repository mhyrr/sketchup-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mhyrr/sketchup-mcp
- Repository: https://github.com/mhyrr/sketchup-mcp

## Overview

SketchupMCP lets an AI client inspect and manipulate a live SketchUp model through MCP tools and a JSON-over-TCP bridge. The principal workflow is a client tool request, Python-side command forwarding, Ruby extension execution, and a response from SketchUp. Tool coverage includes scene and selection inspection, component editing, materials, export, Ruby evaluation, and woodworking joints. The sampled excerpts establish the Python bridge and parts of the Ruby implementation; links to specific Ruby handlers are limited to documented or sampled behavior.

Main entry points: [`su_mcp/su_mcp/main.rb`](https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb) (TCP command server), [`src/sketchup_mcp/server.py`](https://github.com/mhyrr/sketchup-mcp/blob/main/src/sketchup_mcp/server.py) (MCP tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["AI client"]
  node_claude(("Claude / MCP client"))
end

subgraph group_mcp["MCP server"]
  node_tool_server["MCP tools<br/>[server.py]"]
end

subgraph group_bridge["TCP bridge"]
  node_connection["Connection manager<br/>[server.py]"]
end

subgraph group_sketchup["SketchUp extension"]
  node_tcp_server["TCP command server<br/>[main.rb]"]
  node_scene["Scene inspection<br/>[main.rb]"]
  node_selection["Selection handling<br/>[main.rb]"]
  node_components["Component editing<br/>[main.rb]"]
  node_materials["Material control<br/>[main.rb]"]
  node_joints["Woodworking joints<br/>[main.rb]"]
  node_ruby_eval["Ruby evaluation<br/>[main.rb]"]
  node_export["Scene export<br/>[main.rb]"]
  node_model[("Active model")]
end

node_claude -->|"calls tools"| node_tool_server
node_tool_server -->|"forwards commands"| node_connection
node_connection -->|"sends JSON/TCP"| node_tcp_server
node_tcp_server -->|"dispatches"| node_scene
node_tcp_server -->|"dispatches"| node_selection
node_tcp_server -->|"dispatches"| node_components
node_tcp_server -->|"dispatches"| node_materials
node_tcp_server -->|"dispatches"| node_joints
node_tcp_server -->|"dispatches"| node_ruby_eval
node_tcp_server -->|"dispatches"| node_export
node_scene -->|"reads scene"| node_model
node_selection -->|"reads selection"| node_model
node_components -->|"edits entities"| node_model
node_materials -->|"updates materials"| node_model
node_joints -->|"builds joints"| node_model
node_ruby_eval -->|"executes against"| node_model
node_export -->|"exports scene"| node_model

click node_tool_server "https://github.com/mhyrr/sketchup-mcp/blob/main/src/sketchup_mcp/server.py"
click node_connection "https://github.com/mhyrr/sketchup-mcp/blob/main/src/sketchup_mcp/server.py"
click node_tcp_server "https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb"
click node_scene "https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb"
click node_selection "https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb"
click node_components "https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb"
click node_materials "https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb"
click node_joints "https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb"
click node_ruby_eval "https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb"
click node_export "https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claude toneBlue
class node_tool_server toneAmber
class node_connection toneMint
class node_tcp_server,node_scene,node_selection,node_components,node_materials,node_joints,node_ruby_eval,node_export,node_model toneRose
```

## Components

### AI client

- **Claude / MCP client**

### MCP server

- [MCP tools](https://github.com/mhyrr/sketchup-mcp/blob/main/src/sketchup_mcp/server.py): `src/sketchup_mcp/server.py`

### TCP bridge

- [Connection manager](https://github.com/mhyrr/sketchup-mcp/blob/main/src/sketchup_mcp/server.py): `src/sketchup_mcp/server.py`

### SketchUp extension

- [TCP command server](https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb): `su_mcp/su_mcp/main.rb`
- [Scene inspection](https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb): `su_mcp/su_mcp/main.rb`
- [Selection handling](https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb): `su_mcp/su_mcp/main.rb`
- [Component editing](https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb): `su_mcp/su_mcp/main.rb`
- [Material control](https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb): `su_mcp/su_mcp/main.rb`
- [Woodworking joints](https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb): `su_mcp/su_mcp/main.rb`
- [Ruby evaluation](https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb): `su_mcp/su_mcp/main.rb`
- [Scene export](https://github.com/mhyrr/sketchup-mcp/blob/main/su_mcp/su_mcp/main.rb): `su_mcp/su_mcp/main.rb`
- **Active model**

## Connections

- Claude / MCP client → MCP tools: calls tools
- MCP tools → Connection manager: forwards commands
- Connection manager → TCP command server: sends JSON/TCP
- TCP command server → Scene inspection: dispatches
- TCP command server → Selection handling: dispatches
- TCP command server → Component editing: dispatches
- TCP command server → Material control: dispatches
- TCP command server → Woodworking joints: dispatches
- TCP command server → Ruby evaluation: dispatches
- TCP command server → Scene export: dispatches
- Scene inspection → Active model: reads scene
- Selection handling → Active model: reads selection
- Component editing → Active model: edits entities
- Material control → Active model: updates materials
- Woodworking joints → Active model: builds joints
- Ruby evaluation → Active model: executes against
- Scene export → Active model: exports scene