Archicad MCP

Ein MCP-Server für Archicad 29 unter macOS und Windows. Er verbindet Claude Desktop, Claude Code oder einen beliebigen MCP-Client mit einer laufenden Archicad-Instanz und übernimmt zwei Aufgaben:

1. Abnahmebereitschafts-QA. Ihre Bürostandards, geschrieben als YAML-Regeln und ausgeführt gegen das geöffnete Modell. Liefert bestanden/nicht bestanden, eine Punktzahl und die GUIDs der Elemente, die nicht bestanden haben.

2. Voller API-Zugriff. Kuratierte Tools zum Abfragen, Bearbeiten und Erstellen von Elementen, plus ein Gateway zu jedem offiziellen JSON-API- und Tapir-Befehl.

[!WARNING] Speichern Sie, bevor Sie Eigenschaften lesen. GetPropertyValuesOfElements kann Archicad 29 zum Absturz bringen, selbst bei einer einzelnen Eigenschaft an einem einzelnen Element, und ungespeicherte Arbeit mitreißen. Das ist ein Fehler auf Archicad-Seite, den der Server auslösen, aber nicht verhindern kann. Er betrifft audit_delivery_readiness, run_rule, get_element_data und set_element_data. Siehe Bekannte Probleme, bevor Sie das auf ein Modell anwenden, das Ihnen wichtig ist.

Voraussetzungen

• Archicad 29, laufend, mit einem geöffneten Projekt. Die JSON-API kommuniziert mit der aktiven App.

• uv, das den Server installiert und eine passende Python-Version (3.12+) für Sie holt.

• Tapir-Add-on, optional, aber empfohlen. Erforderlich für Elementerstellung, Issues, IFC-Prüfungen, Hervorhebung und Veröffentlichung; verifiziert mit Tapir 1.5.3. Ohne es funktionieren diese Tools eingeschränkt, statt Fehler zu melden.

Related MCP server: redraft

Installation als Claude-Desktop-Erweiterung (empfohlen)

Eine Datei, ein Klick, kein JSON-Bearbeiten. Laden Sie archicad-mcp-0.1.0.mcpb aus dem neuesten Release herunter, und öffnen Sie dann in Claude Desktop Einstellungen > Erweiterungen und ziehen Sie es hinein.

Modus, Ordner für Büroregeln und die Obergrenze für das Lesen von Eigenschaften erscheinen dann als Formularfelder in den Einstellungen der Erweiterung, und der gesamte Server erhält einen Ein/Aus-Schalter. Lassen Sie ein Feld leer, wird der Standardwert aus der Tabelle unten verwendet.

Sie benötigen weiterhin uv auf dem Rechner: Die Erweiterung verwendet es, um beim ersten Start ihre eigene Umgebung aufzubauen, was beim ersten Mal einige Sekunden dauert und danach sofort geht.

Wenn Sie es lieber von Hand einrichten möchten oder Sie Claude Code verwenden, nutzen Sie stattdessen einen der folgenden Abschnitte. Diese installieren das Wheel aus einem getaggten Release, sodass Sie eine bekannte Version erhalten, statt was auch immer main gerade ist. Zum Aktualisieren führen Sie den Installationsbefehl mit der URL der neueren Version von der Release-Seite erneut aus.

Installation unter 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

Bearbeiten Sie ~/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" }
    }
  }
}

Verwenden Sie den absoluten Pfad. Claude Desktop übernimmt nicht die PATH-Variable Ihrer Shell, daher kann ein bloßes "archicad-mcp" in der Regel nicht gestartet werden. Starten Sie Claude Desktop neu, nachdem Sie die Datei bearbeitet haben.

Installation unter 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

Bearbeiten Sie %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" }
    }
  }
}

Backslashes müssen in JSON verdoppelt werden, und die .exe ist wichtig. Starten Sie Claude Desktop nach dem Bearbeiten der Datei neu.

Installation für Claude Code

Claude Code übernimmt die PATH-Variable Ihrer Shell, daher funktioniert der bloße Befehlsname:

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

Prüfen, ob es funktioniert

Bitten Sie den Client bei geöffnetem Archicad, Archicad-Instanzen aufzulisten. Das Tool list_instances meldet den Port, die Version, das geöffnete Projekt und ob Tapir geantwortet hat; das ist der schnellste Weg, ein Konfigurationsproblem von einem Verbindungsproblem zu unterscheiden. Wenn nichts gefunden wird, siehe Bekannte Probleme: Verbindung.

Wenn der Client gar keine Tools anzeigt, wurde der Server nie gestartet, und jede Frage an ihn wird Ihnen nicht sagen, warum. Lesen Sie stattdessen das Protokoll. Der Server schreibt beim Start das, was er gefunden hat, nach stderr, das Claude Desktop erfasst:

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

Diese Zeile unterscheidet die drei Fehler, die im Chatfenster identisch aussehen: Server wurde nicht gestartet (keine Zeile), Archicad läuft nicht (die Zeile sagt das und sagt, dass sich die Tools bei Bedarf verbinden, sobald Sie es starten), und das Tapir-Add-on fehlt (die Zeile nennt, welche Tools eingeschränkt funktionieren).

Konfiguration

Modi

Regeln

Richten Sie ARCHICAD_MCP_RULES_DIR (oder --rules-dir) auf ein Verzeichnis mit YAML-Dateien:

- 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]

Fünf Regeltypen sind eingebaut (property-required, classification-required, layer-compliance, zone-number-required, ifc-property-required), und benutzerdefinierte Prüfungen kommen in eine custom_rules.py neben den YAML-Dateien. Ohne ein Regelverzeichnis werden die mitgelieferten Beispiele geladen, sodass Sie etwas zum Ausführen haben.

Bewahren Sie echte Bürostandards außerhalb dieses Repos in einem lokalen Regelverzeichnis auf.

Vollständige Referenz: docs/rules.md.

Stücklisten

Archicad bietet überhaupt keine API für Stücklisten. Weder die JSON-API, noch Tapir, und laut Graphisoft auch nicht die C++-API. Was es unterstützt, ist der XML-Roundtrip, der in die Schema-Einstellungen eingebaut ist, und darüber arbeiten diese Tools:

1. In Archicad: Dokument > Stücklisten > Schema-Einstellungen, wählen Sie ein Schema, Exportieren

2. Bearbeiten Sie es: read_schedule_scheme, um zu sehen, was es tut, edit_schedule_scheme, um eine YAML-Spezifikation anzuwenden, validate_schedule_scheme, um seine Bindungen gegen das geöffnete Projekt zu prüfen

3. In Archicad: Schema-Einstellungen > Importieren

Eine Schema-Spezifikation sieht so aus:

- 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

Eine Spalte bindet auf drei Arten:

• bind: { property: "<GUID>" }, das keine Verbindung zu Archicad benötigt, oder eine "Group/Name"-Zeichenfolge, die edit_schedule_scheme auflöst, indem es sich mit Archicad verbindet und den Namen nachschlägt. Eine Spezifikation, die nur GUIDs verwendet (plus gdl_param- und builtin-Bindungen, weiter unten), läuft vollständig offline; eine Spezifikation mit auch nur einer benannten Eigenschaft benötigt ein geöffnetes Archicad mit dem Projekt, das sie definiert.

• bind: { gdl_param: "<parameter name>" }, ein Bibliotheksteil-Parameter anhand des Namens

• bind: { builtin: Quantity } für die wenigen benannten integrierten Werte, oder bind: { builtin: { param_type: 0, param_index: -1561 } } für jeden anderen integrierten Wert anhand seiner Rohzahlen

Die benannte Tabelle enthält bewusst nur Quantity: Die Codes dahinter sind undokumentiert und werden empirisch kartiert, ein bestätigtes Beispiel nach dem anderen. Die Rohzahlen-Form ermöglicht es, ein Schema auch dann vollständig auszudrücken, wenn ein integrierter Wert noch keinen Namen hat, und das ist kein seltener Sonderfall: Bei einer echten 27-spaltigen Türliste benötigen 2 Spalten diese Form.

Eine Spalte kann auch width: <number> tragen, das ihre Zellenbreite entsprechend festlegt. Das ist eine Nulloperation, die als solche gemeldet wird, wenn die Spalte bereits diese Breite hat. Nur die Hochformat-Breite ist garantiert: Das Querformat-Breitenfeld wird ebenfalls aktualisiert, wenn eine Spalte bereits eines hat, aber nie bei einer Spalte erzeugt, der es fehlt, da nicht bestätigt ist, dass Archicad selbst dieses Feld für jedes Schema schreibt; das Änderungsprotokoll sagt das deutlich, statt zu raten.

Kriterien werden gelesen und beibehalten, sind aber noch nicht bearbeitbar: Die numerischen Codes dahinter sind undokumentiert und werden in docs/scheme-criteria-codes.md erfasst.

Einschränkungen

• Kriterien werden gelesen und beibehalten, können aber noch nicht bearbeitet werden. Siehe docs/scheme-criteria-codes.md für das, was über die Codes dahinter bisher bestätigt wurde und was noch unbekannt ist.

• Jede Änderung erfordert zwei manuelle Schritte in Archicad, Export vorher und Import nachher, da keine API auf Stücklisten zugreifen kann.

• Ob der erneute Import eines bearbeiteten Schemas dieses an Ort und Stelle aktualisiert oder ein nummeriertes Duplikat erzeugt, ist noch nicht bestätigt. Die Dokumentation von Graphisoft sagt, dass doppelte Namen automatisch nummeriert werden, aber echte Exporte tragen stabile Schema-IDs, was vermuten lässt, dass eine Aktualisierung an Ort und Stelle möglich sein könnte. Testen Sie an einem Testprojekt, bevor Sie sich auf das eine oder andere Verhalten verlassen.

• edit_schedule_scheme lehnt jede Datei ab, die eine No-op-Speicherung nicht unverändert überstehen würde. Das schützt die Teile des Formats, die der Server nicht abbildet.

Tools

QA (beide Modi): list_instances, get_model_summary, list_rules, run_rule, audit_delivery_readiness, verify_ifc_export_readiness, highlight_failures, create_issues_from_failures

Kern (Vollmodus): 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. Jeder Schreibvorgang ist standardmäßig ein Trockenlauf (Dry-run); Löschen und Verschieben erfordern zudem confirm=true.

Gateway (Vollmodus): list_api_commands, describe_api_command, execute_api_command. Der vollständige offizielle + Tapir-Befehlssatz (231 Befehle im verifizierten Setup) für alles, was die kuratierten Tools nicht abdecken.

Entwicklung

uv sync && uv run pytest          # offline suite

Um ein unveröffentlichtes main statt eines Releases zu installieren, richten Sie uv auf das Repository statt auf ein Wheel aus, oder hängen Sie einen Tag an, um eine veröffentlichte Version aus dem Quellcode zu bauen:

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

Live-Tests benötigen ein laufendes Archicad. Öffnen Sie ein kleines, unkritisches Testmodell und legen Sie den Port explizit fest. Führen Sie diese niemals gegen ein Client- oder Teamwork-Projekt aus, und lesen Sie zuerst erneut die Absturz-Warnung oben:

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

Nach einem Update des Tapir-Add-ons aktualisieren Sie die gebündelten Befehlsschemas:

uv run python scripts/sync_tapir_defs.py

Erstellen Sie die Claude-Desktop-Erweiterung. version in manifest.json und in pyproject.toml müssen denselben Wert angeben, und die Testsuite schlägt fehl, wenn sie abweichen:

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 entscheidet, was ausgeliefert wird. Das Bündel enthält pyproject.toml und uv.lock statt mitgelieferter Wheels, sodass uv auf dem Zielrechner denselben festgelegten Abhängigkeitssatz auflöst und ein einziges Bündel sowohl macOS als auch Windows bedient.

Ein Release ist ein Tag-Push. .github/workflows/release.yml weist den Tag zurück, wenn nicht beide Dateien und der Tag selbst in der Version übereinstimmen, und baut dann das Bündel, das Wheel und das sdist und hängt alle drei an ein GitHub-Release an. Führen Sie dieselbe Prüfung zuerst manuell durch, denn ein bereits gepushter Tag muss gelöscht werden, bevor er korrigiert werden kann:

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

icon.png wird generiert, nicht von Hand gezeichnet, sodass es bearbeitbar bleibt. Pillow wird nur zum Neuzeichnen benötigt und ist bewusst keine Projektabhängigkeit:

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

Dokumentation

• Bekannte Probleme: der Absturz beim Lesen von Eigenschaften, die Elementobergrenze, verifizierte Eigenschaftsnamen und was Ende-zu-Ende validiert wird.

• Schreibregeln: jeder Regeltyp, jedes Feld und das Bewertungsmodell.

• Zeitplankriterien-Codes: die empirische Tabelle mit Param_Type und Relation_Index und wie man sie erweitert.

Lizenz

MIT. Siehe LICENSE.