SketchupMCP - Integración del Protocolo de Contexto de Modelo de Sketchup

Originalmente derivado de mhyrr/sketchup-mcp. Se separó en la v0.0.1 con un nuevo protocolo de comunicación (tramado con prefijo de longitud de 4 bytes), arquitectura de manejadores modular, herramientas ampliadas de introspección / ensamblaje / operaciones de aristas, y cobertura total de pruebas unitarias tanto en Ruby como en Python. Publicado en PyPI como sketchup-mcp2 (el paquete original sketchup-mcp es el upstream).

SketchupMCP conecta Sketchup a Claude AI a través del Protocolo de Contexto de Modelo (MCP), permitiendo que Claude interactúe directamente y controle Sketchup. Esta integración permite el modelado 3D asistido por prompts, la creación de escenas y la manipulación en Sketchup.

Un gran agradecimiento a Blender MCP por la inspiración y la estructura.

Características

• Comunicación bidireccional: Conecta Claude AI a Sketchup a través de una conexión de socket TCP

• Manipulación de componentes: Crea, modifica, elimina y transforma componentes en Sketchup

• Control de materiales: Aplica y modifica materiales y colores

• Inspección de escenas: Obtén información detallada sobre la escena actual de Sketchup

• Manejo de selección: Obtén y manipula componentes seleccionados

• Evaluación de código Ruby: Ejecuta código Ruby arbitrario directamente en SketchUp para operaciones avanzadas

Related MCP server: SketchupMCP

Componentes

El sistema consta de dos componentes principales:

1. Extensión de SketchUp (su_mcp/su_mcp/): un plugin modular de Ruby que ejecuta un servidor TCP dentro de SketchUp (core/, handlers/, helpers/).

2. Servidor MCP (src/sketchup_mcp/): un paquete modular de Python construido sobre FastMCP — tools.py expone herramientas MCP, connection.py gestiona el socket TCP persistente con prefijo de longitud de 4 bytes, config.py lee variables de entorno SKETCHUP_MCP_*, errors.py muestra errores estructurados de Ruby.

Instalación

Empaquetado de Python

Estamos usando uv, así que necesitarás ejecutar brew install uv

Extensión de Sketchup

1. Descarga o construye el archivo .rbz más reciente

2. En Sketchup, ve a Ventana > Administrador de extensiones

3. Haz clic en "Instalar extensión" y selecciona el archivo .rbz descargado

4. Reinicia Sketchup

Uso

Iniciar la conexión

1. En Sketchup, ve a Extensiones > SketchupMCP > Iniciar servidor

2. El servidor se iniciará en el puerto predeterminado (9876)

3. Asegúrate de que el servidor MCP esté ejecutándose en tu terminal

Uso con Claude

Configura Claude para usar el servidor MCP añadiendo lo siguiente a tu configuración de Claude:

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

Esto obtendrá la versión más reciente de PyPI

Una vez conectado, Claude puede interactuar con Sketchup usando las siguientes capacidades:

Herramientas

Geometría y transformaciones:

• create_component — Crea un cubo/cilindro/cono/esfera con dimensiones especificadas (mm)

• delete_component — Elimina un componente de la escena

• transform_component — Mueve/rota/escala un componente (traslación en mm)

• set_material — Aplica colores con nombre o hexadecimales (#rrggbb) a un componente

• export_scene — Exporta a skp/obj/dae/stl/png/jpg

Operaciones booleanas y de aristas:

• boolean_operation — Unión/diferencia/intersección en dos sólidos

• chamfer_edge — Bisela todas las aristas de un grupo/componente (distancia en mm)

• fillet_edge — Redondea todas las aristas (radio en mm, segmentos configurables)

Ensamblaje:

• create_mortise_tenon, create_dovetail, create_finger_joint — Uniones de carpintería (dimensiones en mm)

Introspección:

• get_model_info — Ruta, título, unidades, caja delimitadora del modelo activo

• list_components — Árbol de grupos/componentes con cajas delimitadoras (recursivo, profundidad máxima)

• get_component_info — Detalles sobre una entidad por ID

• find_components — Búsqueda por nombre/tipo/capa

• list_layers, create_layer — Gestión de capas/etiquetas

• get_selection — IDs y metadatos de las entidades seleccionadas actualmente

• undo — Deshace la última operación

Salida de emergencia:

• eval_ruby — Ejecuta código Ruby arbitrario en SketchUp para cualquier cosa no cubierta anteriormente

Comandos de ejemplo

Aquí hay algunos ejemplos de lo que puedes pedirle a Claude que haga:

• "Crea un modelo de casa simple con un techo y ventanas"

• "Selecciona todos los componentes y obtén su información"

• "Haz que el componente seleccionado sea rojo"

• "Mueve el componente seleccionado 10 unidades hacia arriba"

• "Exporta la escena actual como un modelo 3D"

• "Crea un gabinete complejo de artes y oficios usando código Ruby"

Solución de problemas

• Problemas de conexión: Asegúrate de que tanto el servidor de la extensión de Sketchup como el servidor MCP estén ejecutándose

• Fallos en los comandos: Revisa la consola de Ruby en Sketchup para ver mensajes de error

• Errores de tiempo de espera: Intenta simplificar tus solicitudes o dividirlas en pasos más pequeños

Detalles técnicos

Protocolo de comunicación

El sistema utiliza un protocolo simple basado en JSON sobre sockets TCP:

• Los comandos se envían como objetos JSON con un type y params opcionales

• Las respuestas son objetos JSON con un status y un result o message

Contribución

¡Las contribuciones son bienvenidas! Por favor, siéntete libre de enviar un Pull Request.

Licencia

MIT

Configuración de MCP

Añade a tu .mcp.json (Claude Code) o configuración de cliente equivalente:

{
  "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"
      }
    }
  }
}

Inicio manual (sin cliente MCP):

uvx sketchup-mcp2

Escenarios complejos

Para trabajar con modelos completos de SketchUp (paredes, techos, marcos, ensamblajes) a través de eval_ruby, consulta los fragmentos de Ruby detallados en docs/sketchup-ruby-cookbook.md:

• «Inspeccionar el modelo abierto» — consultar ruta, capas, caja delimitadora.

• «Crear geometría — asistente confiable make_box» — extrusión segura face.normal.z.

• «Pared enmarcada (montantes + placas)» — sección completa de pared.

• «Pared con apertura» — perforación de agujeros en caras coplanares.

• «Techo a dos aguas / a cuatro aguas» — construcción manual de triángulos.

• «follow_me — perfil a lo largo de una ruta» — solera alrededor del perímetro.

• «Errores comunes» — incluyendo la trampa de semántica invertida de Group#subtract.

Solución de problemas

SketchUp not running or extension not started: ...

El servidor MCP de Python intentó conectarse en el puerto 9876 pero no encontró nada escuchando. O bien:

• SketchUp no se está ejecutando, o

• El plugin MCP está instalado pero no iniciado — abre Plugins → MCP Server → Start.

El servidor permanece activo después de este error; la siguiente llamada a la herramienta reintentará la conexión.