SketchUp MCP Server

Controle o SketchUp com IA. Servidor MCP (Model Context Protocol) que permite que assistentes de IA como Claude, Cursor e Gemini criem modelos 3D programaticamente no SketchUp.

GitHub

Documentação

SketchUp MCP Server

Controle o SketchUp com IA. Servidor MCP (Model Context Protocol) que permite a assistentes de IA como Claude, Cursor e Gemini criar modelos 3D no SketchUp de forma programática.

▶️ Clique aqui para ver o vídeo de demonstração no YouTube

Como Funciona

┌──────────────┐     MCP (stdio)     ┌──────────────┐     HTTP :8080     ┌──────────────┐
│  AI Client   │ ◄──────────────────► │ Python MCP   │ ◄────────────────► │  SketchUp    │
│  (Claude,    │                      │ Server       │                    │  Ruby Plugin │
│   Cursor,    │                      │              │                    │              │
│   Gemini)    │                      │ src/         │                    │  sketchup_   │
│              │                      │ sketchup_mcp/│                    │  plugin/     │
└──────────────┘                      └──────────────┘                    └──────────────┘

O sistema tem dois componentes:

Plugin Ruby (sketchup_plugin/sketchup_mcp_server.rb) — Executa dentro do SketchUp, expõe uma API HTTP em localhost:8080 que controla a API Ruby do SketchUp
Servidor MCP em Python (src/sketchup_mcp/server.py) — Traduz chamadas MCP dos clientes de IA em requisições HTTP para o plugin do SketchUp

Início Rápido

1. Instalar o Plugin do SketchUp

Copie o arquivo Ruby para a pasta de Plugins do SketchUp:

Windows:

Copy-Item "sketchup_plugin\sketchup_mcp_server.rb" "$env:APPDATA\SketchUp\SketchUp 2026\SketchUp\Plugins\" -Force

macOS:

cp sketchup_plugin/sketchup_mcp_server.rb ~/Library/Application\ Support/SketchUp\ 2026/SketchUp/Plugins/

Nota: Substitua 2026 pela sua versão do SketchUp (2024, 2025, etc.)

2. Instalar o Servidor MCP em Python

# 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 seu Cliente de IA

Gemini (Antigravity / Google AI Studio)

Adicione ao seu mcp_config.json:

{
  "mcpServers": {
    "sketchup": {
      "command": "uv",
      "args": [
        "--directory",
        "/RUTA/ABSOLUTA/A/sketchup-mcp",
        "run",
        "sketchup-mcp"
      ]
    }
  }
}

Claude Desktop

Adicione ao claude_desktop_config.json:

{
  "mcpServers": {
    "sketchup": {
      "command": "uv",
      "args": [
        "--directory",
        "/RUTA/ABSOLUTA/A/sketchup-mcp",
        "run",
        "sketchup-mcp"
      ]
    }
  }
}

Localizações do arquivo de configuração:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Alternativa no Windows (sem depender de uv no PATH): após instalar com uv pip install -e . ou pip install -e ., você pode apontar diretamente para o executável do script de console gerado no ambiente virtual:

{
  "mcpServers": {
    "sketchup": {
      "command": "C:\\ruta\\a\\sketchup-mcp\\.venv\\Scripts\\sketchup-mcp.exe"
    }
  }
}

Cursor

Adicione nas configurações MCP (Settings → MCP Servers):

{
  "sketchup": {
    "command": "uv",
    "args": [
      "--directory",
      "/RUTA/ABSOLUTA/A/sketchup-mcp",
      "run",
      "sketchup-mcp"
    ]
  }
}

4. Usar

Abra o SketchUp — O plugin inicia automaticamente o servidor HTTP na porta 8080
Abra seu cliente de IA — O servidor MCP se conecta automaticamente
Peça ao IA para criar geometria — Ex: "Crie uma sala de 3x3x2.5 metros"

Se o servidor não iniciar sozinho, vá para Plugins → MCP Server → Start Server no SketchUp.

Ferramentas Disponíveis (21)

Consulta

Ferramenta	Descrição
`get_model_info`	Informações do modelo: nome, caminho, unidades, contadores
`list_layers`	Listar camadas (tags) com visibilidade
`list_materials`	Listar materiais com cores e texturas
`list_entities`	Listar entidades (faces, arestas, grupos, componentes)
`list_components`	Listar definições de componentes

Criação de Geometria

Ferramenta	Descrição
`create_face`	Criar polígono a partir de pontos 3D ordenados
`create_edge`	Criar segmento de linha entre dois pontos
`create_group`	Criar grupo vazio com nome
`create_box`	Criar caixa (largura × profundidade × altura)
`create_circle`	Criar círculo a partir do centro, normal e raio
`create_arc`	Criar arco com ângulos de início/fim
`create_polygon`	Criar polígono regular (triângulo, pentágono, etc.)

Operações de Geometria

Ferramenta	Descrição
`push_pull`	Extruir uma face a uma distância
`follow_me`	Extruir uma face ao longo de um caminho de arestas

Transformações

Ferramenta	Descrição
`move_entity`	Mover entidade com um vetor
`rotate_entity`	Rotacionar entidade em torno de um eixo
`scale_entity`	Escalar uniforme ou não uniformemente

Componentes

Ferramenta	Descrição
`create_component`	Criar nova definição de componente + instância
`place_component`	Colocar componente existente em uma posição

Construção

Ferramenta	Descrição
`create_roof_truss`	Criar treliças de telhado (king post ou fink)

Avançado

Ferramenta	Descrição
`execute_ruby`	Executar código Ruby arbitrário no SketchUp

Recursos

O servidor inclui recursos de conhecimento sobre construção acessíveis pela IA:

construction://roof-trusses — Guia de design de treliças
construction://framing — Padrões de estrutura
construction://stairs — Padrões de design de escadas

Estrutura do Projeto

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

Solução de Problemas

"Cannot connect to SketchUp"

Certifique-se de que o SketchUp está aberto
Vá para Plugins → MCP Server → Start Server
Verifique se a porta 8080 está livre: netstat -an | findstr 8080 (Windows) ou lsof -i :8080 (macOS)

"Port 8080 already in use"

Feche outras instâncias do SketchUp
Ou mate o processo que usa a porta 8080

O plugin não carrega

Verifique se o arquivo .rb está na pasta de Plugins correta
Verifique o Console Ruby do SketchUp (Window → Ruby Console) para erros
O plugin é um arquivo único e autocontido, não precisa de pastas adicionais

Timeout do servidor

Operações complexas podem demorar mais. O timeout é de 120 segundos.
Se o SketchUp mostrar "não responde", espere até terminar.

Requisitos

SketchUp 2024, 2025 ou 2026
Python 3.10+
uv (recomendado) ou pip

Licença

MIT