# SketchUp MCP Server
> **Controla SketchUp con IA.** Servidor MCP (Model Context Protocol) que permite a asistentes de IA como Claude, Cursor y Gemini crear modelos 3D en SketchUp de forma programática.
## Cómo Funciona
```
┌──────────────┐ MCP (stdio) ┌──────────────┐ HTTP :8080 ┌──────────────┐
│ AI Client │ ◄──────────────────► │ Python MCP │ ◄────────────────► │ SketchUp │
│ (Claude, │ │ Server │ │ Ruby Plugin │
│ Cursor, │ │ │ │ │
│ Gemini) │ │ src/ │ │ sketchup_ │
│ │ │ sketchup_mcp/│ │ plugin/ │
└──────────────┘ └──────────────┘ └──────────────┘
```
El sistema tiene dos componentes:
1. **Plugin Ruby** (`sketchup_plugin/sketchup_mcp_server.rb`) — Se ejecuta dentro de SketchUp, expone una API HTTP en `localhost:8080` que controla la API Ruby de SketchUp
2. **Servidor MCP en Python** (`src/sketchup_mcp/server.py`) — Traduce llamadas MCP de los clientes IA en peticiones HTTP al plugin de SketchUp
## Inicio Rápido
### 1. Instalar el Plugin de SketchUp
Copia el archivo Ruby a la carpeta de Plugins de SketchUp:
**Windows:**
```powershell
Copy-Item "sketchup_plugin\sketchup_mcp_server.rb" "$env:APPDATA\SketchUp\SketchUp 2026\SketchUp\Plugins\" -Force
```
**macOS:**
```bash
cp sketchup_plugin/sketchup_mcp_server.rb ~/Library/Application\ Support/SketchUp\ 2026/SketchUp/Plugins/
```
> **Nota:** Sustituye `2026` por tu versión de SketchUp (2024, 2025, etc.)
### 2. Instalar el Servidor MCP en Python
```bash
# Clona el repositorio
git clone https://github.com/Tarkiin/sketchup-mcp.git
cd sketchup-mcp
# Instalar con uv (recomendado)
uv sync
# O con pip
pip install -e .
```
### 3. Configurar tu Cliente IA
Gemini (Antigravity / Google AI Studio)
Añade a tu `mcp_config.json`:
```json
{
"mcpServers": {
"sketchup": {
"command": "uv",
"args": [
"--directory",
"/RUTA/ABSOLUTA/A/sketchup-mcp",
"run",
"sketchup-mcp"
]
}
}
}
```
Claude Desktop
Añade a `claude_desktop_config.json`:
```json
{
"mcpServers": {
"sketchup": {
"command": "uv",
"args": [
"--directory",
"/RUTA/ABSOLUTA/A/sketchup-mcp",
"run",
"sketchup-mcp"
]
}
}
}
```
Ubicaciones del archivo de configuración:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Alternativa en Windows (sin depender de `uv` en el PATH):** tras instalar con `uv pip install -e .` o `pip install -e .`, puedes apuntar directamente al ejecutable del script de consola generado en el entorno virtual:
```json
{
"mcpServers": {
"sketchup": {
"command": "C:\\ruta\\a\\sketchup-mcp\\.venv\\Scripts\\sketchup-mcp.exe"
}
}
}
```
Cursor
Añade en los ajustes MCP (Settings → MCP Servers):
```json
{
"sketchup": {
"command": "uv",
"args": [
"--directory",
"/RUTA/ABSOLUTA/A/sketchup-mcp",
"run",
"sketchup-mcp"
]
}
}
```
### 4. Usar
1. **Abre SketchUp** — El plugin arranca automáticamente el servidor HTTP en el puerto 8080
2. **Abre tu cliente IA** — El servidor MCP se conecta automáticamente
3. **Pide al IA que cree geometría** — Ej: *"Crea una habitación de 3x3x2.5 metros"*
Si el servidor no arranca solo, ve a `Plugins → MCP Server → Start Server` en SketchUp.
## Tools Disponibles (21)
### Consulta
| Tool | Descripción |
|------|-------------|
| `get_model_info` | Info del modelo: nombre, ruta, unidades, contadores |
| `list_layers` | Listar capas (tags) con visibilidad |
| `list_materials` | Listar materiales con colores y texturas |
| `list_entities` | Listar entidades (caras, aristas, grupos, componentes) |
| `list_components` | Listar definiciones de componentes |
### Creación de Geometría
| Tool | Descripción |
|------|-------------|
| `create_face` | Crear polígono a partir de puntos 3D ordenados |
| `create_edge` | Crear segmento de línea entre dos puntos |
| `create_group` | Crear grupo vacío con nombre |
| `create_box` | Crear caja (ancho × fondo × alto) |
| `create_circle` | Crear círculo desde centro, normal y radio |
| `create_arc` | Crear arco con ángulos de inicio/fin |
| `create_polygon` | Crear polígono regular (triángulo, pentágono, etc.) |
### Operaciones de Geometría
| Tool | Descripción |
|------|-------------|
| `push_pull` | Extruir una cara a una distancia |
| `follow_me` | Extruir una cara a lo largo de un camino de aristas |
### Transformaciones
| Tool | Descripción |
|------|-------------|
| `move_entity` | Mover entidad con un vector |
| `rotate_entity` | Rotar entidad alrededor de un eje |
| `scale_entity` | Escalar uniforme o no uniformemente |
### Componentes
| Tool | Descripción |
|------|-------------|
| `create_component` | Crear nueva definición de componente + instancia |
| `place_component` | Colocar componente existente en una posición |
### Construcción
| Tool | Descripción |
|------|-------------|
| `create_roof_truss` | Crear cerchas de techo (king post o fink) |
### Avanzado
| Tool | Descripción |
|------|-------------|
| `execute_ruby` | Ejecutar código Ruby arbitrario en SketchUp |
## Recursos
El servidor incluye recursos de conocimiento sobre construcción accesibles por la IA:
- `construction://roof-trusses` — Guía de diseño de cerchas
- `construction://framing` — Estándares de estructura
- `construction://stairs` — Estándares de diseño de escaleras
## Estructura del Proyecto
```
sketchup-mcp/
├── src/
│ └── sketchup_mcp/
│ ├── __init__.py # Entry point del paquete
│ ├── __main__.py # Soporte python -m
│ └── server.py # Servidor MCP (Python)
├── sketchup_plugin/
│ └── sketchup_mcp_server.rb # Plugin Ruby para SketchUp
├── resources/ # Archivos de conocimiento de construcción
├── pyproject.toml
├── .gitignore
├── LICENSE
└── README.md
```
## Solución de Problemas
### "Cannot connect to SketchUp"
- Asegúrate de que SketchUp está abierto
- Ve a `Plugins → MCP Server → Start Server`
- Comprueba si el puerto 8080 está libre: `netstat -an | findstr 8080` (Windows) o `lsof -i :8080` (macOS)
### "Port 8080 already in use"
- Cierra otras instancias de SketchUp
- O mata el proceso que usa el puerto 8080
### El plugin no carga
- Verifica que el archivo `.rb` está en la carpeta de Plugins correcta
- Comprueba la Ruby Console de SketchUp (`Window → Ruby Console`) para errores
- El plugin es un archivo único y autocontenido, no necesita carpetas adicionales
### Timeout del servidor
- Operaciones complejas pueden tardar más. El timeout es de 120 segundos.
- Si SketchUp muestra "no responde", espera a que termine.
## Requisitos
- **SketchUp** 2024, 2025 o 2026
- **Python** 3.10+
- **uv** (recomendado) o pip
## Licencia
MIT
