Skip to main content
Glama
Archicad MCP

Archicad MCP

Archicad MCP

MCP-сервер для Archicad через аддон Tapir. Даёт модели проектные данные (стены, плиты, зоны, свойства, этажи) и умеет строить и править модель, не заваливая её контекст семьюстами схемами.

Что нужно

  • Archicad 25–30 (поддерживается установленным Tapir).

  • Аддон Tapir 2.0 внутри Archicad: ставится инсталлятором с релиз-страницы, после установки аддон нужно один раз включить в Options → Add-On Manager: строка «Tapir Additional JSON Commands», галочка слева. Сам файл лежит в Program Files\Graphisoft\Archicad NN\Add-Ons\Tapir\TapirAddOn_ACNN_Win.apx.

  • Python 3.11+ для самого сервера.

Tapir слушает 127.0.0.1:19723–19743 — первый запущенный Archicad занимает 19723, следующий свободный. Сервер сам находит живой порт при первом вызове.

Related MCP server: archicad-mcp

Установка

python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .

Проверка, что пакет жив (Archicad не нужен):

.venv\Scripts\archicad-mcp.exe --list-tools

Подключение

{
  "mcpServers": {
    "archicad": {
      "command": "D:\\path\\to\\Archicad MCP\\.venv\\Scripts\\archicad-mcp.exe",
      "env": { "ARCHICAD_MCP_MODE": "safe" }
    }
  }
}

Переменные окружения:

Переменная

По умолчанию

Что делает

ARCHICAD_MCP_MODE

safe

readonly / safe / full — см. ниже

ARCHICAD_MCP_PORT

—

прибить один порт вместо перебора

ARCHICAD_MCP_HOST

127.0.0.1

адрес

ARCHICAD_MCP_TIMEOUT

60

таймаут одного вызова, секунды

ARCHICAD_MCP_RESULT_BUDGET

12000

сколько символов ответа отдавать целиком

Режимы

Режим

Чтение

Изменения

Разрушающее (Delete*, Quit, Close)

readonly

да

отказ

отказ

safe

да

да

только dry-run, применение — по confirm=true

full

да

да

как есть

Интерактивные команды (GetPointFromUser, диалоги, ScriptUI) блокируются везде, кроме full: они останавливаются и ждут клика в Archicad, то есть подвешивают вызов.

Инструменты

Чтение и состояние: archicad_status, project_info, stories, find_elements, selected_elements, element_details.

Свойства: search_properties, get_property_values, set_property_values, resolve_names. Свойства задаются именами — сервер сам достаёт id через SearchProperties.

Имена свойств Tapir отдаёт внутренние, без пробелов: ElementID, Home Story, Type, группа GeneralElemProperties. С пробелом тоже можно: Element ID найдётся, сервер сравнивает имена без пробелов и знаков.

Создание и правка: create_walls, create_slabs, create_zones, select_elements, delete_elements.

Остальные ~770 команд Tapir (публикация, IFC, сметы, навигатор, MEP, отделки):

  1. search_commands("publish pdf") — найти (у каждой находки есть kind: read / write / destructive / interactive);

  2. describe_command("PublishPublisherSet") — прочитать аргументы, форму ответа и строку Policy: о том, что текущий режим сделает с этой командой;

  3. run_command("PublishPublisherSet", {...}) — вызвать.

Большие ответы обрезаются до бюджета, в них остаётся блок _truncated с resultId, total и showing. Дальше read_result(result_id, offset, limit) — постраничное чтение.

Аргументы проверяются до отправки: если у команды нет такого аргумента, ответ будет CreateWalls does not take dryRun. Accepted arguments: wallsData. вместо ответа Archicad о нарушении правила JSON-схемы. Важная деталь: dryRun поддерживают не все команды — у CreateWalls его нет, у DeleteElements и SetPropertyValuesOfElements есть.

find_elements и selected_elements отдают готовые guid-строки, их можно сразу передавать в element_details, get_property_values, select_elements, delete_elements.

Как это устроено

  • defs.py — читает вендоренные определения Tapir (src/archicad_mcp/tapir/*.js, 789 команд), разворачивает $ref, печатает сигнатуры.

  • client.py — HTTP к Archicad: обёртка API.ExecuteAddOnCommand, поиск порта, человеческие ошибки (NotRunning, AddOnMissing, TimedOut, PortNotTapir, CommandFailed).

  • classify.py — политика режимов.

  • compact.py — обрезка ответов и хранилище полных версий.

  • search.py — BM25 по именам и описаниям команд.

  • tools.py — сами инструменты, server.py — регистрация в MCP.

Тесты

.venv\Scripts\python.exe -m pytest -q

Архикада в тестах нет: FakeTransport из tests/conftest.py отвечает вместо него, поэтому проверяется логика сервера, а не живой Archicad. Живой прогон — первый запуск через MCP-клиент.

Проверено на живом Archicad

Archicad 26.0.0 R1 (build 5002) + Tapir 2.0.0, на настоящем рабочем проекте:

python scripts\live_check.py
{"port": 19723, "tapirAddOn": "2.0.0", "archicad": 26, "archicadBuild": 5002,
 "language": "RUS", "mode": "safe", "connected": true, "commandsAvailable": 789}

Что это дало по фактам, а не по документации:

  • Язык приходит полем languageCode, а не language.

  • GetElementsByType в пустом проекте честно отдаёт пусто; в реальном — столько, сколько есть объектов нужного типа.

  • GetPropertyValuesOfElements отвечает без id свойств, значения идут в том же порядке, в котором их спросили, — сервер раскладывает их по именам сам.

  • Имена свойств внутренние: ElementID, Type, группа GeneralElemProperties.

  • CreateWalls не принимает dryRun, поэтому превью создания стены невозможно: проверка только через аргументы и ответ Archicad.

  • ChangeSelectionOfElements и GetSelectedElements работают: {"action":"added","requested":3,"done":3}, затем {"count":4,...} — четвёртый элемент уже был выделен до вызова.

  • DeleteElements с dryRun отвечает {"requested":1,"done":1} и строкой Note: … was previewed only: dryRun was switched on. Nothing changed.

  • CreateWalls работает: две стены (0,0)→(5,0) и (0,0)→(0,5) с floorIndex: 0, height: 3, thickness: 0.2, structureType: "Basic" появились в проекте, получили id СТН-003 и СТН-004 и читаются обратно через element_details(..., ["details"]) теми же координатами.

  • Геометрия лежит не в отдельном поле, а внутри details: fields принимает только elementId, type, id, floorIndex, layerIndex, drawIndex, details, floorPlanPolygons, hotlinkId. Просьба fields: ["begCoordinate"] теперь ловится до отправки и перечисляет допустимые значения.

Когда Archicad занят

Пока в Archicad открыт модальный диалог, аддон отвечает на всё одной и той же ошибкой:

{"succeeded": false, "error": {"code": 4001,
 "message": "Invalid program status (there is an open modal dialog: Параметры Объекта по Умолчанию)"}}

Падает даже проба GetAddOnVersion, поэтому раньше сервер честно врал «аддон не установлен». Теперь он различает эти случаи и пишет:

{"error": "Archicad has a dialog open (Параметры Объекта по Умолчанию), so it cannot run commands.",
 "hint": "Close the dialog in Archicad, then call again. Nothing was changed."}

Повтора нет: пока диалог открыт, любой вызов упрётся в то же самое. Для чтения сервер делает один тихий повтор на случай, когда Archicad занят предыдущей командой; для изменения — никогда, потому что повторный DeleteElements может удалить уже другое.

Ограничения

  • Tapir 1.x не поддерживается: используются команды, появившиеся в 2.0.

  • На живом Archicad 26 проверены состояние, проект, этажи, поиск элементов, выделение, детали, свойства, resolve_names, превью удаления, создание стен и люк run_command.

  • create_slabs и create_zones проверены только схемой и фейком: для плиты нужен полигон с уровнем, для зоны — категория и геометрия, и проверять их лучше на черновом проекте.

  • create_walls принимает данные Tapir как есть (метры, begCoordinate/endCoordinate), без разбора PDF или DWG.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP server for Archicad automation, enabling AI assistants to run Python scripts against running Archicad instances via the Tapir JSON API for complex workflows.
      4
      167 PyPI
      8
      MIT
    • F
      license
      A
      quality
      B
      maintenance
      Read-only MCP bridge for Archicad using the Tapir Add-On, enabling discovery, context binding, and safe read operations on Archicad projects.
      8
      -