Archicad MCP

Archicad 29용 MCP 서버로, macOS와 Windows에서 동작합니다. Claude Desktop, Claude Code 또는 모든 MCP 클라이언트를 실행 중인 Archicad 인스턴스에 연결하며 두 가지 작업을 수행합니다:

1. 납품 준비 상태 QA. 사무소 표준을 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에서 설정 > 확장 프로그램을 열고 끌어다 놓으세요.

모드, 사무소 규칙 폴더, 속성 읽기 상한은 확장 프로그램 설정의 양식 필드로 표시되며, 전체 서버에는 켜기/끄기 스위치가 있습니다. 필드를 비워 두면 아래 표의 기본값으로 대체됩니다.

여전히 머신에 uv가 필요합니다. 확장 프로그램은 첫 실행 시 자체 환경을 구축하는 데 uv를 사용하며, 첫 번째는 몇 초, 이후에는 즉시 완료됩니다.

직접 연결하거나 Claude Code를 사용하는 경우 아래 섹션 중 하나를 사용하세요. 해당 섹션은 태그가 지정된 릴리스에서 휠을 설치하므로 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). 사용자 지정 검사는 YAML 옆의 custom_rules.py에 작성합니다. 규칙 디렉터리가 없으면 번들된 예제가 로드되어 실행할 수 있는 것이 준비됩니다.

실제 사무소 표준은 이 저장소 외부의 로컬 규칙 디렉터리에 두세요.

전체 참조: docs/rules.md.

스케줄

Archicad는 스케줄에 대한 API를 전혀 제공하지 않습니다. JSON API도, Tapir도, Graphisoft에 따르면 C++ API도 없습니다. 지원하는 것은 Scheme Settings에 내장된 XML 왕복이며, 이 도구들은 이를 통해 작동합니다:

1. Archicad에서: 문서 > 스케줄 > Scheme Settings에서 스킴을 선택하고 내보내기

2. 편집: read_schedule_scheme로 현재 동작 확인, edit_schedule_scheme로 YAML 사양 적용, validate_schedule_scheme로 열린 프로젝트에 대한 바인딩 검증

3. Archicad에서: Scheme Settings > 가져오기

스킴 사양은 다음과 같습니다:

- 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에서 수동 단계가 두 번 필요합니다. 스케줄에 도달하는 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

핵심 (full 모드): 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. 모든 쓰기는 기본적으로 드라이런이며, 삭제와 이동은 confirm=true도 필요합니다.

게이트웨이 (full 모드): list_api_commands, describe_api_command, execute_api_command. 검증된 설정에서 231개 명령의 전체 공식 + Tapir 명령 표면으로, 선별된 도구가 다루지 않는 모든 것을 처리합니다.

개발

uv sync && uv run pytest          # offline suite

릴리스 대신 미출시 main을 설치하려면 uv를 휠 대신 저장소를 가리키게 하거나, 태그를 추가하여 소스에서 릴리스 버전을 빌드하세요:

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가 필요합니다. 작고 중요하지 않은 테스트 모델을 열고 포트를 명시적으로 고정하세요. 클라이언트 또는 팀워크 프로젝트에 대해 실행하지 말고, 위의 충돌 경고를 다시 읽으세요:

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

Tapir 애드온 업데이트 후 번들된 명령 스키마를 새로 고치세요:

uv run python scripts/sync_tapir_defs.py

Claude Desktop 확장 프로그램을 빌드하세요. manifest.json의 version과 pyproject.toml의 version이 동일해야 하며, 테스트 스위트는 불일치 시 실패합니다:

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이 포함되므로, 대상 머신에서 uv가 동일한 고정 종속성 세트를 해결하고 하나의 번들이 macOS와 Windows 모두에 사용됩니다.

릴리스는 태그 푸시입니다. .github/workflows/release.yml은 두 파일과 태그 자체가 버전에 동의하지 않으면 태그를 거부한 다음 번들, 휠, 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 참조.