Blender 2D MCP

Dibujo y animación 2D impulsados por IA para Blender 5.x mediante el Model Context Protocol. Permite que los clientes MCP (Claude Desktop, Cursor, modo agente de VS Code Copilot, …) creen dibujos de Grease Pencil, fotogramas clave, materiales y renderizados directamente dentro de una instancia de Blender en ejecución.

Construido sobre la API GPv3 de Blender (bpy.ops.grease_pencil.*, GreasePencilDrawing), modelado según ahujasid/blender-mcp.

flowchart LR
    A[MCP Client<br/>Claude / Cursor / VS Code] <-->|stdio / JSON-RPC| B[blender-2d-mcp<br/>FastMCP server]
    B <-->|TCP JSON<br/>localhost:9876| C[addon.py<br/>socket server in Blender]
    C -->|main thread| D[Grease Pencil API<br/>GPv3]

• addon.py — Complemento de Blender que incorpora un servidor de comandos TCP JSON. Los comandos se ponen en cola y se ejecutan en el hilo principal de Blender mediante bpy.app.timers.

• src/blender_2d_mcp/server.py — Servidor stdio FastMCP que expone los comandos del complemento como herramientas MCP.

Requisitos

• Solo Blender 5.2 LTS (el complemento se niega a activarse en versiones anteriores; la superficie de la API GPv3 que utiliza es específica de 5.2)

• Python ≥ 3.10 con mcp[cli] (se instala automáticamente)

Related MCP server: Blender MCP Bridge

Instalación

1. Instalar el complemento en Blender

1. En Blender: Editar > Preferencias > Complementos > Instalar…

2. Selecciona addon.py de este repositorio.

3. Activa Interfaz: Blender 2D MCP.

4. Abre la barra lateral (Ver > Barra lateral, o pulsa N) → pestaña Blender2DMCP.

5. Haz clic en Conectar al cliente MCP (puerto predeterminado 9876). Mantén Blender en ejecución.

Consejo: blender-2d-mcp --install-addon copia addon.py a tu carpeta de Descargas e imprime estos pasos.

2. Conectar un cliente MCP

El servidor se vincula solo a localhost; no se necesita token de autenticación para uso local.

Opción A — uvx (sin instalación):

uvx --from "g:\My Projects\blender-2d-mcp" blender-2d-mcp

Opción B — instalación editable:

cd "g:\My Projects\blender-2d-mcp"
pip install -e .
blender-2d-mcp            # runs the stdio MCP server

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "blender-2d-mcp": {
      "command": "uvx",
      "args": ["--from", "g:\\My Projects\\blender-2d-mcp", "blender-2d-mcp"]
    }
  }
}

Cursor (.cursor/mcp.json) o clientes stdio genéricos:

{
  "mcpServers": {
    "blender-2d-mcp": {
      "command": "C:\\Path\\To\\Python\\Scripts\\blender-2d-mcp.exe",
      "args": []
    }
  }
}

VS Code / GitHub Copilot Chat (.vscode/mcp.json — ya incluido en este repositorio):

{
  "servers": {
    "blender-2d-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "g:\\My Projects\\blender-2d-mcp", "blender-2d-mcp"],
      "env": {}
    }
  }
}

Alternativamente, si blender_2d_mcp está instalado con pip en algún entorno, usa el Python de ese entorno: "command": "C:\\Path\\To\\Python\\python.exe", "args": ["-m", "blender_2d_mcp.server"].

Para usarlo: abre Copilot Chat, cambia el menú desplegable de modo a Agente, y las herramientas de Blender estarán disponibles (#blender-2d-mcp). Inicia/detén/reinicia el servidor desde la Paleta de comandos con MCP: List Servers. Recarga la ventana de VS Code después de editar mcp.json.

El lienzo 2D

Con setup_2d_scene la vista se establece en una vista ortográfica frontal, por lo que el plano de dibujo es el mundo XZ:

Las unidades son metros (predeterminado de Blender); un fotograma HD de 1920×1080 con el zoom de cámara predeterminado abarca aproximadamente ±5 unidades horizontalmente.

Catálogo de herramientas

Flujo de trabajo típico

1. get_gp_scene_info + get_viewport_screenshot — ver lo que existe.

2. setup_2d_scene → create_gp_object si se empieza desde cero.

3. Dibuja con gp_draw_shape / gp_draw_stroke; pasa frame_number para colocar trazos en poses clave (los fotogramas se crean automáticamente). Usa gp_draw_strokes para dibujos detallados por lotes.

4. Formas rellenas: crea un material con fill_alpha > 0, luego fill=True + fill_material.

5. Anima 'en dos' (poses clave cada 2 fotogramas a 24 fps): copia poses con gp_copy_frame, ajusta con gp_transform_stroke, luego gp_interpolate para interpolaciones. Añade un modificador NOISE para el temblor a mano alzada.

6. Renderiza con render_animation(use_video=True) y consulta get_render_status.

7. Siempre captura la pantalla después de los cambios para verificar visualmente. Los errores se pueden deshacer con undo.

Desarrollo

pip install -e ".[dev]"
python -m pytest tests/ -v

El conjunto de pruebas ejecuta el transporte TCP del complemento fuera de Blender mediante el levantamiento AST de la clase de servidor contra un bpy falso; no se necesita instalación de Blender. La lógica de los manejadores que toca datos reales de Grease Pencil debe verificarse dentro de Blender.

Solución de problemas

Licencia

MIT