Archicad MCP

MCP-сервер для Archicad 29 на macOS и Windows. Он подключает Claude Desktop, Claude Code или любой MCP-клиент к запущенному экземпляру Archicad и выполняет две задачи:

1. Проверка готовности к сдаче. Ваши офисные стандарты, описанные как YAML-правила, применяются к открытой модели. Возвращается результат прохождения/непрохождения, оценка и GUID элементов, которые не прошли проверку.

2. Полный доступ к API. Подобранные инструменты для запроса, редактирования и создания элементов, а также шлюз ко всем официальным командам JSON API и Tapir.

[!WARNING] Сохранитесь перед чтением свойств. GetPropertyValuesOfElements может вызвать сбой Archicad 29, даже для одного свойства одного элемента, унося с собой несохранённую работу. Это ошибка на стороне Archicad, которую сервер может спровоцировать, но не может предотвратить. Она затрагивает audit_delivery_readiness, run_rule, get_element_data и set_element_data. См. Известные проблемы, прежде чем направлять это на модель, которая вам дорога.

Требования

• Archicad 29, запущенный, с открытым проектом. JSON API общается с работающим приложением.

• uv, который устанавливает сервер и подбирает подходящий Python (3.12+) для вас.

• Дополнение Tapir, необязательное, но рекомендуемое. Требуется для создания элементов, задач, проверок IFC, подсветки и публикации; проверено на Tapir 1.5.3. Без него эти инструменты деградируют, а не выдают ошибку.

Related MCP server: redraft

Установка как расширения Claude Desktop (рекомендуется)

Один файл, один клик, без редактирования JSON. Загрузите archicad-mcp-0.1.0.mcpb из последнего релиза, затем в Claude Desktop откройте Settings > Extensions и перетащите его туда.

Режим, папка офисных правил и предел чтения свойств затем появляются как поля формы в настройках расширения, а весь сервер получает переключатель вкл/выкл. Если оставить поле пустым, оно вернётся к значению по умолчанию из таблицы ниже.

Вам всё ещё нужен uv на машине: расширение использует его для создания собственного окружения при первом запуске, что занимает несколько секунд в первый раз и мгновенно впоследствии.

Если вы предпочитаете настроить вручную или используете Claude Code, воспользуйтесь одним из разделов ниже. Они устанавливают wheel из помеченного релиза, поэтому вы получаете известную версию, а не то, чем main окажется на данный момент. Чтобы обновиться, повторно выполните команду установки с URL более новой версии со страницы релизов.

Установка на macOS

# 1. Install uv (skip if you already have it)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Install the server from the latest release
uv tool install https://github.com/alesdev88/Archicad-MCP/releases/download/v0.1.0/archicad_mcp-0.1.0-py3-none-any.whl

# 3. Note the path (you need it for the config below)
which archicad-mcp        # ~/.local/bin/archicad-mcp

Отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "archicad": {
      "command": "/Users/YOU/.local/bin/archicad-mcp",
      "args": ["--mode", "full"],
      "env": { "ARCHICAD_MCP_RULES_DIR": "/Users/YOU/office-rules" }
    }
  }
}

Используйте абсолютный путь. Claude Desktop не наследует PATH вашей оболочки, поэтому голое "archicad-mcp" обычно не запускается. Перезапустите Claude Desktop после редактирования файла.

Установка на Windows

# 1. Install uv (skip if you already have it)
winget install --id=astral-sh.uv -e

# 2. Install the server from the latest release
uv tool install https://github.com/alesdev88/Archicad-MCP/releases/download/v0.1.0/archicad_mcp-0.1.0-py3-none-any.whl

# 3. Note the path (you need it for the config below)
where.exe archicad-mcp    # %USERPROFILE%\.local\bin\archicad-mcp.exe

Отредактируйте %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "archicad": {
      "command": "C:\\Users\\YOU\\.local\\bin\\archicad-mcp.exe",
      "args": ["--mode", "full"],
      "env": { "ARCHICAD_MCP_RULES_DIR": "C:\\Users\\YOU\\office-rules" }
    }
  }
}

В JSON обратные слэши должны быть удвоены, а .exe важен. Перезапустите Claude Desktop после редактирования файла.

Установка для Claude Code

Claude Code наследует PATH вашей оболочки, поэтому голое имя команды работает:

uv tool install https://github.com/alesdev88/Archicad-MCP/releases/download/v0.1.0/archicad_mcp-0.1.0-py3-none-any.whl
claude mcp add archicad -- archicad-mcp --mode full

Проверка работы

При открытом Archicad попросите клиент перечислить экземпляры Archicad. Инструмент list_instances сообщает порт, версию, открытый проект и ответил ли Tapir, что является самым быстрым способом отличить проблему конфигурации от проблемы подключения. Если ничего не найдено, см. Известные проблемы: подключение.

Если клиент не показывает никаких инструментов вообще, сервер не запустился, и любые вопросы к нему не объяснят причину. Вместо этого прочитайте лог. При запуске сервер записывает в stderr то, что он обнаружил, а Claude Desktop перехватывает это:

tail -20 ~/Library/Logs/Claude/mcp-server-archicad.log   # %APPDATA%\Claude\logs on Windows

archicad-mcp: mode=full, 12 rules loaded
archicad-mcp: Archicad 29 (build 4006) on port 19723, project 'Sample', Tapir 1.5.3

Эта строка различает три сбоя, которые выглядят одинаково в окне чата: сервер не запускается (вообще нет строки), Archicad не запущен (строка сообщает об этом и говорит, что инструменты подключаются по требованию, как только вы его запустите) и отсутствует дополнение Tapir (строка называет инструменты, которые деградируют).

Конфигурация

Режимы

Правила

Укажите ARCHICAD_MCP_RULES_DIR (или --rules-dir) на каталог с YAML-файлами:

- id: walls-fire-rating
  type: property-required
  property: "OFFICE/Fire Rating"   # user properties are "Group/Name"
  applies_to: { element_type: Wall }
  severity: error
  tags: [ifc-delivery]

Пять типов правил встроены (property-required, classification-required, layer-compliance, zone-number-required, ifc-property-required), а пользовательские проверки помещаются в custom_rules.py рядом с YAML. Если каталог правил не указан, загружаются встроенные примеры, чтобы было что запускать.

Держите реальные офисные стандарты вне этого репозитория, в локальном каталоге правил.

Полная документация: docs/rules.md.

Ведомости

Archicad вообще не предоставляет API для ведомостей. Ни JSON API, ни Tapir, и, по словам Graphisoft, ни C++ API тоже. Что он поддерживает — это XML-цикл, встроенный в Scheme Settings, и именно через него работают эти инструменты:

1. В Archicad: Document > Schedules > Scheme Settings, выберите схему, Export

2. Отредактируйте её: read_schedule_scheme — посмотреть её содержимое, edit_schedule_scheme — применить YAML-спецификацию, validate_schedule_scheme — проверить её привязки на открытом проекте

3. В Archicad: Scheme Settings > Import

Спецификация схемы выглядит так:

- id: door-schedule
  template: exports/door-scheme.xml
  name: "Door Schedule"
  columns:
    - caption: "Quantity"
      bind: { builtin: Quantity }
    - caption: "Fire Resistance"
      bind: { gdl_param: "Fire Rating" }
      width: 40

Колонка привязывается тремя способами:

• bind: { property: "<GUID>" } — не требует подключения к Archicad, или строка "Group/Name", которую edit_schedule_scheme разрешает, подключаясь к Archicad и выполняя поиск по имени. Спецификация, использующая только GUID (плюс привязки gdl_param и builtin, см. ниже), работает полностью офлайн; спецификация хотя бы с одним именованным свойством требует открытого Archicad с проектом, в котором оно определено.

• bind: { gdl_param: "<parameter name>" } — параметр библиотечного объекта по имени

• bind: { builtin: Quantity } — для немногих именованных встроенных, или bind: { builtin: { param_type: 0, param_index: -1561 } } — для любой другой встроенной по её числовым кодам

Именованная таблица намеренно содержит только Quantity: коды за ней не документированы и отображаются эмпирически, по одному подтверждённому примеру за раз. Форма с числовыми кодами позволяет полностью выразить схему даже тогда, когда у встроенной ещё нет имени, и это не редкий крайний случай: в реальной ведомости дверей с 27 колонками 2 колонки требуют этого.

Колонка также может содержать width: <number>, который устанавливает ширину её ячейки. Это холостая операция, о чём и сообщается, если колонка уже имеет эту ширину. Гарантируется только книжная ширина: поле альбомной ширины также обновляется, если колонка уже имеет его, но никогда не создаётся у колонки, где его нет, поскольку не подтверждено, что Archicad сам пишет это поле для каждой схемы, и журнал изменений говорит об этом прямо, а не гадает.

Критерии читаются и сохраняются, но пока не редактируются: числовые коды за ними не документированы, и их сопоставление ведётся в docs/scheme-criteria-codes.md.

Ограничения

• Критерии читаются и сохраняются, но пока не могут быть отредактированы. См. docs/scheme-criteria-codes.md, что уже подтверждено о кодах за ними, а что всё ещё неизвестно.

• Каждое редактирование требует два ручных шага в Archicad: Export до и Import после, потому что ни один API не добирается до ведомостей.

• Пока не подтверждено, обновляет ли повторный импорт отредактированной схемы её на месте или создаёт пронумерованную копию. Документация Graphisoft говорит, что дубликаты имён автоматически нумеруются, но реальные экспорты содержат стабильные ID схем, что предполагает возможное совпадение на месте. Проверьте на черновом проекте, прежде чем полагаться на любое из поведений.

• edit_schedule_scheme отказывается от любого файла, который не переживёт холостого сохранения без изменений. Это защищает те части формата, которые сервер не моделирует.

Инструменты

QA (оба режима): list_instances, get_model_summary, list_rules, run_rule, audit_delivery_readiness, verify_ifc_export_readiness, highlight_failures, create_issues_from_failures

Основные (полный режим): query_elements, get_element_data, set_element_data, create_elements, move_elements, delete_elements, manage_selection, get_project_info, list_attributes, manage_issues, publish, read_schedule_scheme, edit_schedule_scheme, validate_schedule_scheme. Каждая операция записи по умолчанию выполняется в режиме dry-run; удаление и перемещение также требуют confirm=true.

Шлюз (полный режим): list_api_commands, describe_api_command, execute_api_command. Полная поверхность официальных команд + Tapir (231 команда в проверенной конфигурации) для всего, что не покрывают подобранные инструменты.

Разработка

uv sync && uv run pytest          # offline suite

Чтобы установить невыпущенный main, а не релиз, укажите uv на репозиторий вместо wheel или добавьте тег для сборки выпущенной версии из исходников:

uv tool install git+https://github.com/alesdev88/Archicad-MCP.git          # main
uv tool install git+https://github.com/alesdev88/Archicad-MCP.git@v0.1.0   # a release

Живые тесты требуют запущенного Archicad. Откройте небольшую, не содержащую чувствительных данных тестовую модель и явно укажите порт. Никогда не запускайте их на клиентском или teamwork-проекте и сначала перечитайте предупреждение о сбое выше:

ARCHICAD_MCP_LIVE_PORT=<port> uv run pytest -m live -v

После обновления дополнения Tapir обновите встроенные схемы команд:

uv run python scripts/sync_tapir_defs.py

Соберите расширение Claude Desktop. version в manifest.json и в pyproject.toml должны совпадать, и набор тестов падает, если они расходятся:

uv run python scripts/check_release_version.py
npx @anthropic-ai/mcpb validate manifest.json && npx @anthropic-ai/mcpb pack . dist/archicad-mcp-0.1.0.mcpb

.mcpbignore определяет, что попадает в поставку. Пакет несёт pyproject.toml и uv.lock, а не вендоренные wheel, поэтому uv разрешает тот же набор закреплённых зависимостей на целевой машине, и один пакет подходит и для macOS, и для Windows.

Релиз — это отправка тега. .github/workflows/release.yml отказывает тегу, если оба файла и сам тег не согласуются по версии, затем собирает пакет, wheel и sdist и прикрепляет все три к релизу GitHub. Сначала выполните ту же проверку вручную, потому что тег, который уже отправлен, нужно удалить, прежде чем его можно будет исправить:

uv run python scripts/check_release_version.py v0.1.1
git tag v0.1.1 && git push origin v0.1.1

icon.png генерируется, а не рисуется вручную, поэтому остаётся редактируемым. Pillow нужен только для его перерисовки и намеренно не является зависимостью проекта:

uv run --with pillow python scripts/make_icon.py

Документация

• Известные проблемы: сбой чтения свойств, потолок элементов, проверенные имена свойств и что проверяется сквозным образом.

• Правила написания: каждый тип правила, поле и модель оценки.

• Коды критериев расписания: эмпирическая таблица Param_Type и Relation_Index и способы её расширения.

Лицензия

MIT. См. LICENSE.