onshape-mcp

Servidor MCP que impulsa OnShape CAD desde Claude Code: modelado paramétrico (bocetos, extrusiones, revoluciones, empalmes, patrones), consultas de FeatureScript y exportación/verificación de STL, mediante la API REST de OnShape.

Configuración inicial

uv sync --no-editable
uv run --no-editable onshape-mcp setup    # writes ~/.config/onshape-mcp/.env (chmod 600); no-op if it exists
uv run --no-editable onshape-mcp doctor   # auth smoke test against the live API (4 calls)

¿Por qué --no-editable en todas partes? macOS marca de forma asíncrona los archivos bajo .venv con el atributo hidden, y Python ≥3.13.8 omite los archivos .pth ocultos — las instalaciones editables dejan de importar silenciosamente minutos después de una sincronización. Las instalaciones no editables no usan .pth y son inmunes.

Related MCP server: MCP 3D Printer Server

Credenciales

Las claves de API provienen de https://dev-portal.onshape.com/keys (clave de acceso y clave secreta). Las credenciales viven SOLO en ~/.config/onshape-mcp/.env, creado por onshape-mcp setup con permisos 600 (solo lectura/escritura del propietario) — nunca en carpetas del proyecto, nunca en el repositorio, nunca se imprimen. Consulta .env.example para los nombres de las variables; el entorno del proceso (ONSHAPE_ACCESS_KEY / ONSHAPE_SECRET_KEY) tiene prioridad sobre el archivo si ambos existen.

Registro por proyecto

Desde la carpeta del proyecto CAD donde quieras que el servidor esté disponible (sustituye /path/to/onshape-mcp por donde hayas clonado este repositorio):

/path/to/onshape-mcp/install.sh

o de forma equivalente:

claude mcp add --scope project onshape -- \
  uv run --quiet --no-editable --project /path/to/onshape-mcp onshape-mcp

o regístralo manualmente en el .mcp.json del proyecto:

{
  "mcpServers": {
    "onshape": {
      "command": "uv",
      "args": ["run", "--quiet", "--no-editable", "--project", "/path/to/onshape-mcp", "onshape-mcp"]
    }
  }
}

(--project, no --directory: el servidor resuelve el venv de este repositorio pero conserva el directorio actual del llamador. Los parámetros de rutas de archivo de las herramientas deben ser rutas absolutas de todos modos.) Las servidores de proyecto muestran “Pendiente de aprobación” en la primera sesión interactiva: aprueba cuando se te solicite.

Referencia rápida de uso (para el LLM que maneja las herramientas)

Flujo típico de construcción

create_document (parentId = folder id)   -> documentId, workspaceId, partStudioElementId
import_cad (ABSOLUTE path to .zip/STEP)  -> foreign CAD into an existing workspace [async, +quota]
set_variable (optional, e.g. wall_thk)   -> use "#wall_thk" in later expressions
create_sketch (plane {"default":"TOP"})  -> featureId            [one closed profile per sketch]
extrude (sketchFeatureId, NEW, depth)    -> base solid
create_sketch + extrude REMOVE THROUGH_ALL                       [holes: skip native hole feature]
find_entities (EDGE, radiusBetween)      -> transient ids for fillet/chamfer
fillet_or_chamfer (entityIds)            -> check featureStatus == OK after EVERY feature
pattern / revolve / boolean_parts as needed
export_stl (ABSOLUTE path)               -> compare_stl(candidate, reference)  [mesh: 3D-print, verify]
export_step (ABSOLUTE path)              -> editable STEP B-rep solid           [CAD/prototyping; async, +quota]

Reglas de hierro

1. Los IDs transitorios caducan DESPUÉS de cualquier mutación. Llama siempre a find_entities inmediatamente antes de la herramienta que consuma dichos IDs. Los IDs de features (de create\_sketch/extrude/...) son estables — úsalos donde se acepten (regiones de extrude, semillas de patrón, cuerpos booleanos).

2. Unidades: los parámetros y resultados de las herramientas están en pulgadas por defecto (parámetro units para cambiar). Las cadenas de dimensión se pasan tal cual: "1.53 in", "25 mm", "#wall_thk * 2". Los ángulos se miden en grados. Los resultados crudos de eval_featurescript están en METROS/radianes.

3. featureStatus es el bucle de regeneración: OK significa continuar; ERROR significa que el feature se añadió pero falló — corrige los parámetros con update_feature o delete_feature y reintenta. Compruébalo después de cada llamada de modelado.

4. extrude REMOVE resta de TODOS los sólidos del estudio (defaultScope). Mantén una sola pieza por estudio salvo que esa sea tu intención.

5. Un solo perfil cerrado por sketch mantiene clara la selección de la región de extrude.

6. Las rutas de archivo deben ser ABSOLUTAS (el cwd del servidor no es el del proyecto).

7. Sé prudente: ~2,500 llamadas de API al AÑO. No hagas polling ni vuelvas a listar sin necesidad; de todas formas analyze\_stl/compare\_stl cuestan cero llamadas.

Aviso de cuota

Las cuentas EDU/Free de OnShape tienen una cuota anual de API (~2,500 llamadas/usuario/año); al agotarse devuelve 402 y ningún backoff lo soluciona. Este servidor mantiene un contador persistente en ~/.config/onshape-mcp/call_log y un total acumulado por stderr. Supervisa el uso en OnShape en Mi cuenta → Desarrollador.

Desarrollo

uv run --no-editable pytest          # offline tests (no API calls, no credentials needed)
uv run --no-editable onshape-mcp doctor

Licencia

MIT — consulta LICENSE.