onshape-mcp

MCP-сервер, который управляет OnShape CAD из Claude Code: параметрическое моделирование (эскизы, выдавливания, вращения, скругления, массивы), запросы FeatureScript и экспорт/проверка STL — через REST API OnShape.

Одноразовая настройка

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)

Почему везде --no-editable? macOS асинхронно помечает файлы в .venv флагом hidden, и Python ≥3.13.8 пропускает скрытые .pth-файлы — редактируемые установки молча перестают импортироваться через несколько минут после синхронизации. Нередактируемые установки не используют .pth, поэтому не затронуты.

Related MCP server: MCP 3D Printer Server

Учётные данные

API-ключи берутся с https://dev-portal.onshape.com/keys (пара access key и secret key). Учётные данные хранятся ТОЛЬКО в ~/.config/onshape-mcp/.env, создаваемом командой onshape-mcp setup с правами 600 (чтение/запись только для владельца) — никогда в папках проектов, никогда в коммитах, никогда не печатаются. Имена переменных см. в .env.example; переменные окружения (ONSHAPE_ACCESS_KEY / ONSHAPE_SECRET_KEY) имеют приоритет над файлом, если заданы обе.

Регистрация на уровне проекта

Из папки CAD-проекта, где нужен сервер (замените /path/to/onshape-mcp на путь, по которому вы клонировали этот репозиторий):

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

или эквивалентно:

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

Или зарегистрируйте его вручную в .mcp.json проекта:

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

(--project, а не --directory: сервер находит venv этого репозитория, но сохраняет рабочую директорию вызывающей команды. Параметры инструментов с путями к файлам всё равно должны быть абсолютными.)

Серверы уровня проекта при первой интерактивной сессии показывают «Pending approval» — одобрите по запросу.

Шпаргалка по использованию (для LLM, управляющего инструментами)

Типовой процесс моделирования

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]

Железные правила

1. Временные ID устаревают после ЛЮБОГО изменения. Всегда вызывайте find_entities непосредственно перед вызовом инструмента, который потребляет эти ID. ID функций (из create_sketch/extrude/...) стабильны — предпочитайте их там, где они принимаются (области выдавливания, исходные тела для массивов, тела для булевых операций).

2. Единицы измерения: параметры инструментов и результаты по умолчанию в дюймах (параметр units для изменения). Размерные строки передаются как есть: "1.53 in", "25 mm", "#wall_thk * 2". Углы — в градусах. Сырые результаты eval_featurescript — в МЕТРАХ/радианах.

3. featureStatus — контур обратной связи при регенерации: OK — продолжайте; ERROR — функция добавлена, но не удалась — исправьте параметры через update_feature или delete_feature и повторите. Проверяйте его после каждого вызова моделирования.

4. extrude REMOVE вычитает из ВСЕХ тел в студии (defaultScope). Держите одну деталь в студии, если не нужно иное.

5. Один замкнутый профиль на эскиз обеспечивает однозначность выбора области выдавливания.

6. Пути к файлам должны быть АБСОЛЮТНЫМИ (рабочая директория сервера не равна рабочей директории проекта).

7. Экономьте: около 2 500 вызовов API в ГОД. Не выполняйте поллинг, не запрашивайте списки повторно без необходимости; analyze_stl/compare_stl стоят ноль вызовов.

Предупреждение о квоте

Учётные записи OnShape EDU/Free имеют годовую квоту API (около 2 500 вызовов/пользователь/год); при исчерпании возвращается 402, и никакой backoff этого не исправит. Этот сервер ведёт постоянный счётчик вызовов в ~/.config/onshape-mcp/call_log и выводит накапливаемый итог в stderr. Следите за расходом в OnShape: My Account → Developer.

Разработка

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

Лицензия

MIT — см. LICENSE.