max2021-mcp

Puente estable HTTP + TCP + MCP para ejecutar Python y MaxScript dentro de Autodesk 3ds Max 2021, pensado para agentes de Cursor (u otros clientes MCP).

Basado en boa-control-max (MIT), con parches y workflow verificados en Max 2021.3.6.

Arquitectura

Cursor (MCP stdio)
    └─ packages/max-mcp-server   →  HTTP localhost:8123
           └─ packages/max-server (Node)
                  └─ TCP 127.0.0.1:7603
                         └─ bridge Python dentro de 3ds Max (PySide2)
                                └─ ejecuta código y responde por HTTP

Pieza	Puerto	Rol
max-server	8123	API HTTP + SSE
Bridge en Max	7603	TCP (arranca con startup de Max)
max-mcp-server	stdio	Tools MCP executePyCode / executeMxsCode

Requisitos

• Windows + 3ds Max 2021
• Node.js 18+
• pnpm (npm i -g pnpm)
• Cursor (u otro cliente MCP)

Instalación (máquina nueva)

git clone https://github.com/patriciojuliant/max2021-mcp.git
cd max2021-mcp
pnpm install

# 1) Registra el startup de Max (bridge TCP :7603 al abrir Max)
.\scripts\Install-MaxStartup.ps1

# 2) Escribe/actualiza ~/.cursor/mcp.json
.\scripts\Install-CursorMcp.ps1

# 3) Arranca HTTP :8123 (+ Max si hace falta)
.\scripts\Start-Max2021Mcp.ps1

Reiniciá Cursor después de Install-CursorMcp.ps1.

Uso diario

.\scripts\Start-Max2021Mcp.ps1
# o solo el bridge HTTP si Max ya está abierto:
.\scripts\Start-Max2021Mcp.ps1 -NoMax

Health check:

.\scripts\Test-Health.ps1

Fallback manual en el Listener de Max:

fileIn @"<REPO>\packages\max-server\src\max-utils\start_max2021_mcp.ms"

Tools MCP

• executePyCode — preferido. Dejá el valor en result (JSON-serializable).
• executeMxsCode — solo si Python no alcanza.

Ejemplo Python:

import pymxs
rt = pymxs.runtime
result = {"ok": True, "version": str(rt.maxVersion())}

¿Por qué este fork?

El upstream asume qtpy y paths de Max más nuevos. En Max 2021:

• hay que usar PySide2 (no qtpy)
• hace falta un startup script para el TCP :7603
• el HTTP :8123 no vive dentro de Max; hay que levantarlo aparte
• si falta :8123, Cursor muestra fetch failed aunque Max esté abierto

Detalle de incidentes y fixes: docs/TROUBLESHOOTING.md.

Licencia

MIT — ver LICENSE y NOTICE.