SketchupMCP - Sketchup Model Context Protocol Integration

Ursprünglich ein Fork von mhyrr/sketchup-mcp. Ab v0.0.1 mit einem neuen Wire-Protokoll (4-Byte Längenpräfix-Framing), modularer Handler-Architektur, erweiterten Introspektions-, Tischler- und Kantenbearbeitungswerkzeugen sowie vollständiger Unit-Test-Abdeckung sowohl für Ruby als auch für Python abgewichen. Veröffentlicht auf PyPI als sketchup-mcp2 (das ursprüngliche sketchup-mcp Paket ist das Upstream-Projekt).

SketchupMCP verbindet Sketchup über das Model Context Protocol (MCP) mit Claude AI, sodass Claude direkt mit Sketchup interagieren und es steuern kann. Diese Integration ermöglicht prompt-gestützte 3D-Modellierung, Szenenerstellung und Manipulation in Sketchup.

Ein großes Dankeschön an Blender MCP für die Inspiration und Struktur.

Funktionen

• Zwei-Wege-Kommunikation: Verbinden Sie Claude AI über eine TCP-Socket-Verbindung mit Sketchup

• Komponentenmanipulation: Erstellen, ändern, löschen und transformieren Sie Komponenten in Sketchup

• Materialsteuerung: Wenden Sie Materialien und Farben an und ändern Sie diese

• Szeneninspektion: Erhalten Sie detaillierte Informationen über die aktuelle Sketchup-Szene

• Auswahlverarbeitung: Abrufen und Manipulieren ausgewählter Komponenten

• Ruby-Code-Ausführung: Führen Sie beliebigen Ruby-Code direkt in SketchUp für fortgeschrittene Operationen aus

Related MCP server: SketchupMCP

Komponenten

Das System besteht aus zwei Hauptkomponenten:

1. SketchUp-Erweiterung (su_mcp/su_mcp/): ein modulares Ruby-Plugin, das einen TCP-Server innerhalb von SketchUp ausführt (core/, handlers/, helpers/).

2. MCP-Server (src/sketchup_mcp/): ein modulares Python-Paket, das auf FastMCP basiert — tools.py stellt MCP-Tools bereit, connection.py verwaltet den persistenten TCP-Socket mit 4-Byte Längenpräfix-Framing, config.py liest SKETCHUP_MCP_* Umgebungsvariablen, errors.py gibt strukturierte Ruby-Fehler aus.

Installation

Python-Paketierung

Wir verwenden uv, daher müssen Sie brew install uv ausführen.

Sketchup-Erweiterung

1. Laden Sie die neueste .rbz-Datei herunter oder erstellen Sie sie

2. Gehen Sie in Sketchup auf Fenster > Extension Manager

3. Klicken Sie auf "Install Extension" und wählen Sie die heruntergeladene .rbz-Datei aus

4. Starten Sie Sketchup neu

Verwendung

Starten der Verbindung

1. Gehen Sie in Sketchup auf Extensions > SketchupMCP > Start Server

2. Der Server startet auf dem Standardport (9876)

3. Stellen Sie sicher, dass der MCP-Server in Ihrem Terminal läuft

Verwendung mit Claude

Konfigurieren Sie Claude für die Verwendung des MCP-Servers, indem Sie Folgendes zu Ihrer Claude-Konfiguration hinzufügen:

    "mcpServers": {
        "sketchup": {
            "command": "uvx",
            "args": [
                "sketchup-mcp2"
            ]
        }
    }

Dies lädt die neueste Version von PyPI

Sobald die Verbindung hergestellt ist, kann Claude mit Sketchup unter Verwendung der folgenden Funktionen interagieren:

Werkzeuge

Geometrie & Transformationen:

• create_component — Erstellen Sie einen Würfel/Zylinder/Kegel/Kugel mit angegebenen Abmessungen (mm)

• delete_component — Entfernen Sie eine Komponente aus der Szene

• transform_component — Verschieben/Rotieren/Skalieren einer Komponente (Translation in mm)

• set_material — Wenden Sie benannte oder Hex-Farben (#rrggbb) auf eine Komponente an

• export_scene — Exportieren nach skp/obj/dae/stl/png/jpg

Boolesche Operationen & Kantenbearbeitung:

• boolean_operation — Vereinigung/Differenz/Schnittmenge bei zwei Volumenkörpern

• chamfer_edge — Fasen Sie alle Kanten einer Gruppe/Komponente (Abstand in mm)

• fillet_edge — Runden Sie alle Kanten ab (Radius in mm, Segmente konfigurierbar)

Tischlerarbeiten:

• create_mortise_tenon, create_dovetail, create_finger_joint — Holzverbindungen (Abmessungen in mm)

Introspektion:

• get_model_info — Pfad, Titel, Einheiten, Bounding Box des aktiven Modells

• list_components — Baumstruktur von Gruppen/Komponenten mit Bounding Boxes (rekursiv, max_depth)

• get_component_info — Details zu einer Entität nach ID

• find_components — Suche nach Name/Typ/Layer

• list_layers, create_layer — Layer-/Tag-Verwaltung

• get_selection — IDs und Metadaten der aktuell ausgewählten Entitäten

• undo — Letzte Operation rückgängig machen

Notausgang:

• eval_ruby — Führen Sie beliebigen Ruby-Code in SketchUp für alles aus, was oben nicht abgedeckt ist

Beispielbefehle

Hier sind einige Beispiele dafür, was Sie Claude fragen können:

• "Erstelle ein einfaches Hausmodell mit Dach und Fenstern"

• "Wähle alle Komponenten aus und rufe deren Informationen ab"

• "Färbe die ausgewählte Komponente rot"

• "Verschiebe die ausgewählte Komponente um 10 Einheiten nach oben"

• "Exportiere die aktuelle Szene als 3D-Modell"

• "Erstelle einen komplexen Arts-and-Crafts-Schrank mit Ruby-Code"

Fehlerbehebung

• Verbindungsprobleme: Stellen Sie sicher, dass sowohl der Sketchup-Erweiterungsserver als auch der MCP-Server laufen

• Befehlsfehler: Überprüfen Sie die Ruby-Konsole in Sketchup auf Fehlermeldungen

• Timeout-Fehler: Versuchen Sie, Ihre Anfragen zu vereinfachen oder in kleinere Schritte zu unterteilen

Technische Details

Kommunikationsprotokoll

Das System verwendet ein einfaches JSON-basiertes Protokoll über TCP-Sockets:

• Befehle werden als JSON-Objekte mit einem type und optionalen params gesendet

• Antworten sind JSON-Objekte mit einem status und result oder message

Mitwirken

Beiträge sind willkommen! Bitte zögern Sie nicht, einen Pull Request einzureichen.

Lizenz

MIT

MCP-Konfiguration

Fügen Sie dies zu Ihrer .mcp.json (Claude Code) oder einer äquivalenten Client-Konfiguration hinzu:

{
  "mcpServers": {
    "sketchup": {
      "command": "uvx",
      "args": ["sketchup-mcp2"],
      "env": {
        "SKETCHUP_MCP_HOST": "127.0.0.1",
        "SKETCHUP_MCP_PORT": "9876",
        "SKETCHUP_MCP_TIMEOUT": "60",
        "SKETCHUP_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Manueller Start (kein MCP-Client):

uvx sketchup-mcp2

Komplexe Szenarien

Für die Arbeit mit vollständigen SketchUp-Modellen (Wände, Dächer, Rahmen, Verbindungen) über eval_ruby, siehe die detaillierten Ruby-Snippets in docs/sketchup-ruby-cookbook.md:

• «Inspect the open model» — Pfad, Layer, Bounding Box abfragen.

• «Create geometry — reliable make_box helper» — face.normal.z sichere Extrusion.

• «Framed wall (studs + plates)» — vollständiger Wandabschnitt.

• «Wall with opening» — Lochstanzung in koplanaren Flächen.

• «Gable / hip roof» — manuelle Dreieckskonstruktion.

• «follow_me — profile along a path» — Mauerlatte entlang des Umfangs.

• «Common pitfalls» — einschließlich der Group#subtract Falle bei umgekehrter Semantik.

Fehlerbehebung

SketchUp not running or extension not started: ...

Der Python-MCP-Server hat versucht, sich über Port 9876 zu verbinden, fand aber nichts, das auf Verbindungen wartet. Entweder:

• SketchUp läuft nicht, oder

• Das MCP-Plugin ist installiert, aber nicht gestartet — öffnen Sie Plugins → MCP Server → Start.

Der Server bleibt nach diesem Fehler aktiv; der nächste Tool-Aufruf versucht die Verbindung erneut.