Archicad

Archicad MCP

An MCP server for Archicad 29 on macOS and Windows. It connects Claude Desktop, Claude Code, ChatGPT, or any MCP client to a running Archicad instance and does two jobs:

1. Delivery-readiness QA. Your office standards, written as YAML rules and run against the open model. Returns pass/fail, a score, and the GUIDs of the elements that failed.
2. Full API access. Curated tools for querying, editing, and creating elements, plus a gateway to every official JSON API and Tapir command.

[!WARNING] Save before you read properties. GetPropertyValuesOfElements can crash Archicad 29, even for a single property on a single element, taking unsaved work with it. This is an Archicad-side fault the server can trigger but cannot prevent. It affects audit_delivery_readiness, run_rule, get_element_data, and set_element_data. Ask the client to run save_project first. See Known issues before you point this at a model you care about.

Requirements

• Archicad 29, running, with a project open. The JSON API talks to the live app.
• Nothing else, if you install the extension. The .mcpb carries its own Python interpreter and every dependency, so there is nothing to install first and nothing to download on first launch. The manual install paths below do need uv, which fetches a suitable Python (3.12+) for you.
• Tapir add-on, optional but recommended, and installed for you: run archicad-mcp install-tapir, or ask the client to run the install_tapir tool (see Install Tapir). Required for element creation, issues, IFC checks, highlighting, and publishing. The installer puts the pinned Tapir 1.7.1 in place, checked by sha256. The bundled command definitions are synced from Tapir 1.7.1; create_elements has been exercised live against 1.7.1 on Archicad 29 and 30, the other tools against 1.5.9 or later. A newer add-on than the definitions is fine. Without the add-on, the tools that need it say which file to install, and the rest degrade instead of erroring.

Install as a Claude Desktop extension (recommended)

One file, one click, no JSON editing, and no prerequisites. Download the bundle for your platform from the latest release:

There is no Intel macOS bundle. cryptography, which this server depends on through FastMCP, no longer publishes macOS x86_64 wheels, so that bundle could only be produced by compiling on an Intel Mac. Intel Macs use the manual install below instead, where the build happens on the machine that will run it.

Then in Claude Desktop open Settings > Extensions and drag it in.

Mode, office rules folder, and the property-read ceiling then appear as form fields in the extension's settings, and the whole server gets an on/off switch. Leave a field empty and it falls back to the default in the table below.

The bundle contains a complete CPython 3.12 and every dependency, so it starts immediately and works on a machine with no Python, no uv, and no internet access. That is why it is 42 MB on Windows and 54 MB on macOS: the alternative was asking every machine to install a package manager first.

Deploying to a team? On a Team or Enterprise plan an owner can upload the bundle under Organization settings > Connectors > Desktop, which makes it a one-click install for everyone instead of a file to pass around.

If you would rather wire it up by hand, or you are on Claude Code, use one of the sections below instead. Those install the server from PyPI, where it is published as archicad-mcp-server (the plain name was already taken by an unrelated project), so uv tool upgrade archicad-mcp-server moves you to the next release. Each section also shows the wheel URL of the current release, for when you want to pin exactly this version rather than whatever PyPI holds when you run the command.

Install on macOS

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

# 2. Install the server from PyPI
uv tool install archicad-mcp-server
#    or pin this exact release instead:
#    uv tool install https://github.com/alesdev88/Archicad-MCP/releases/download/v0.10.0/archicad_mcp_server-0.10.0-py3-none-any.whl

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

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

Use the absolute path. Claude Desktop does not inherit your shell's PATH, so a bare "archicad-mcp" usually fails to spawn. Restart Claude Desktop after editing the file.

Install on Windows

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

# 2. Install the server from PyPI
uv tool install archicad-mcp-server
#    or pin this exact release instead:
#    uv tool install https://github.com/alesdev88/Archicad-MCP/releases/download/v0.10.0/archicad_mcp_server-0.10.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

Edit %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 must be doubled in JSON, and the .exe matters. Restart Claude Desktop after editing the file.

Install for Claude Code

Claude Code inherits your shell's PATH, so the bare command name works:

uv tool install archicad-mcp-server
# or pin this exact release instead:
# uv tool install https://github.com/alesdev88/Archicad-MCP/releases/download/v0.10.0/archicad_mcp_server-0.10.0-py3-none-any.whl
claude mcp add archicad -- archicad-mcp --mode full

Use with ChatGPT

ChatGPT only talks to remote MCP servers over HTTPS. It cannot spawn a local server the way Claude Desktop does, and this server has to run on the machine that runs Archicad, because it reaches Archicad on localhost. So the recipe is: serve over HTTP on the Archicad machine, tunnel that to a public HTTPS URL, and register the URL as a custom connector.

[!CAUTION] Whoever reaches that URL drives your open Archicad model: every property is readable, and in full mode elements can be edited, deleted, and published. ChatGPT custom connectors authenticate with OAuth or not at all, so this server adds no token of its own. Put access control in front of the tunnel (Cloudflare Access, ngrok's OAuth or IP restrictions), prefer --mode verdicts, and stop the server when you are done.

The --transport flag is newer than the first release. If archicad-mcp --help does not list it, install from main as described under Development.

# 1. On the Archicad machine, serve over HTTP. Binds to localhost only.
archicad-mcp --mode verdicts --transport http --http-port 8000

# 2. In a second terminal, tunnel it. One of:
cloudflared tunnel --url http://localhost:8000
ngrok http 8000

The tunnel prints a public URL. The MCP endpoint is that URL plus /mcp.

3. In ChatGPT on the web, open Settings > Connectors > Advanced and turn on Developer mode. Then Settings > Connectors > Create: name it Archicad, paste https://<your-tunnel>/mcp as the URL, tick I trust this provider, and create it. Developer mode needs a Plus, Pro, Business, Enterprise, or Edu account; without it ChatGPT rejects any server that lacks search and fetch tools.
4. In a new chat, open + > More > Developer mode and enable the Archicad connector. This is per chat.

Then ask it to list Archicad instances, as under Check it works. The crash warning at the top applies to every client, ChatGPT included.

Codex instead of ChatGPT. OpenAI's Codex CLI runs stdio servers directly, so there is no tunnel and nothing leaves the machine:

codex mcp add archicad -- archicad-mcp --mode full

Install Tapir

Tapir is a C++ add-on that runs inside Archicad, so it has to sit in Archicad's Add-Ons folder; a server outside Archicad cannot carry its commands. The server installs it for you:

archicad-mcp install-tapir --dry-run

That lists every Archicad on the computer and the Tapir each one has, downloads the pinned Tapir release for each listed Archicad version (also where a Tapir is already there, to tell whether it is the same file), checks each file's sha256 against the value committed in this repository, and says what it would do. Without --dry-run it shows the same plan and asks before writing anything. Restart Archicad afterwards.

The Claude Desktop extension puts no command on your PATH, so from there ask Claude to install Tapir: the install_tapir tool does the same, as a dry run first and with confirm=true to write.

An existing Tapir is never touched by default. It is listed with its path, its date, and whether it is byte-identical to the pinned release, and skipped. With --replace (or replace_existing=true) it is moved, never deleted, to ~/Library/Application Support/archicad-mcp/tapir-backups/AC<version>-<date>/ (%LOCALAPPDATA%\archicad-mcp\tapir-backups\ on Windows), with a backup.json saying where each piece came from. A custom Tapir build loses its own commands when it is replaced. A Tapir that Archicad loads from another folder through Add-On Manager cannot be moved aside, so it is left alone even then; remove it in Add-On Manager first.

Tapir goes into Add-Ons/Tapir/, where Tapir's own installer puts it, so Tapir's Check for Updates keeps working afterwards.

When the Add-Ons folder needs administrator rights: on macOS the system password dialog appears. On Windows, where Archicad lives under Program Files, nothing changes and the result gives the exact command to run from a terminal opened as administrator (for the extension, its own bundled Python running -m archicad_mcp.tapir_install), plus the steps to hand to IT. The Windows path is covered by unit tests only so far.

By hand: download TapirAddOn_AC<version>_Mac.zip or TapirAddOn_AC<version>_Win.apx for your Archicad version from the Tapir 1.7.1 release, unzip it (macOS) or copy it (Windows) into Add-Ons/Tapir/ inside the Archicad folder, and restart Archicad.

Check it works

With Archicad open, ask the client to list Archicad instances. The list_instances tool reports the port, version, open project, and whether Tapir answered, which is the fastest way to tell a config problem from a connection problem. When Tapir is missing, or lacks commands a tool needs, the instance carries a tapir_hint naming the exact file and the install command. If nothing is found, see Known issues: connection.

If the client shows no tools at all, the server never started, and asking it anything will not tell you why. Read the log instead. The server writes what it found to stderr on startup, which Claude Desktop captures:

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 5101) on port 19723, project 'Sample', Tapir 1.5.9

That line distinguishes the three failures that look identical from the chat window: the server not spawning (no line at all), Archicad not running (the line says so, and says tools connect on demand once you start it), and the Tapir add-on missing (the line names which tools degrade and the install command).

Configuration

Modes

Rules

The server loads rules from one directory, and where that directory is set depends on how the server was installed. Nothing else is read: the bundled examples load only when no directory is set.

Use an absolute path. A relative one resolves against whatever working directory the client happened to spawn the server in.

Check what actually loaded before trusting an audit. The startup line in the log says where the rules came from and how many there are:

archicad-mcp: mode=full, 1 rule loaded from /Users/YOU/office-rules
archicad-mcp: mode=full, 3 bundled example rules loaded (no rules directory set)

and list_rules returns the same source plus every rule id and any file that failed to parse. A low count with the right directory usually means the file holds templates that are still commented out, which is how the starter file ships. The count is of rules, not files.

A rule file is a YAML list of rules:

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

Six rule types ship built in (property-required, classification-required, layer-compliance, zone-number-required, ifc-property-required, no-collisions), and custom checks go in a custom_rules.py beside the YAML. Without a rules directory, the bundled examples load so you have something to run.

Keep real office standards outside this repo, in a local rules directory.

Full reference: docs/rules.md.

Schedules

Archicad exposes no API for schedules at all. Not the JSON API, not Tapir, and per Graphisoft not the C++ API either. What it does support is the XML round trip built into Scheme Settings, and that is what these tools work through:

1. In Archicad: Document > Schedules > Scheme Settings, select a scheme, Export
2. Edit it: read_schedule_scheme to see what it does, edit_schedule_scheme to apply a YAML spec, validate_schedule_scheme to check its bindings against the open project
3. In Archicad: Scheme Settings > Import

A scheme spec looks like this:

- 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

A column binds three ways:

• bind: { property: "<GUID>" }, which needs no connection to Archicad, or a "Group/Name" string, which edit_schedule_scheme resolves by connecting to Archicad and looking the name up. A spec that only uses GUIDs (plus gdl_param and builtin bindings, below) runs fully offline; a spec with even one named property needs Archicad open with the project that defines it.
• bind: { gdl_param: "<parameter name>" }, a library part parameter by name
• bind: { builtin: Quantity } for the few named built-ins, or bind: { builtin: { param_type: 0, param_index: -1561 } } for any other built-in by its raw numbers

The named table deliberately holds only Quantity: the codes behind it are undocumented and are being mapped empirically, one confirmed example at a time. The raw-numbers form is what lets a scheme still be fully expressed even when a built-in has no name yet, and this is not a rare corner case: on a real 27-column door schedule, 2 columns need it.

A column can also carry width: <number>, which sets its cell width to match. This is a no-op, reported as such, when the column already has that width. Only the portrait width is guaranteed: the landscape width field is updated too when a column already has one, but is never created on a column that lacks it, since that has not been confirmed as a field Archicad itself writes for every scheme, and the change log says so plainly rather than guessing.

Criteria are read and preserved but not yet editable: the numeric codes behind them are undocumented and are being mapped in docs/scheme-criteria-codes.md.

Limitations

• Criteria are read and preserved but cannot yet be edited. See docs/scheme-criteria-codes.md for what is confirmed about the codes behind them so far, and what is still unknown.
• Every edit needs two manual steps in Archicad, Export before and Import after, because no API reaches schedules.
• Whether re-importing an edited scheme updates it in place or creates a numbered duplicate is not yet confirmed. Graphisoft's documentation says duplicate names are auto-numbered, but real exports carry stable scheme IDs, which suggests an in-place match may be possible. Test on a scratch project before relying on either behaviour.
• edit_schedule_scheme refuses any file that would not survive a no-op save unchanged. This protects the parts of the format the server does not model.

Library parts

Mesh models (OBJ, 3DS) become placeable Archicad library parts without opening the GDL editor. The pipeline parses the mesh (units, pivots, welding), optionally decimates dense meshes through a background Blender, writes the HSF source, compiles it with the LP_XMLConverter bundled inside Archicad, and deploys over the same connection the server uses. Finish variants become dropdowns in Object Settings. See the GDL pipeline guide.

There are two ways in.

From an MCP client, using list_gdl_sources, inspect_gdl_source, build_gdl_object and deploy_gdl_object. Set the GDL workspace folder in the extension settings, and add that same folder to Archicad once via File > Libraries and Objects > Library Manager. Source meshes and textures go in it by hand; everything the tools write lands there too. Building needs no project open. Deploying reloads libraries, places the object, renders it and returns the image, then deletes the instance it placed unless you pass keep=true.

That render is the point. Archicad silently drops defective 3D bodies while every offline validator passes them, so looking at the picture is the only automated check that catches it.

This route runs inside the server process, so it works from clients whose agent has no shell on the machine running Archicad, which includes any sandboxed one.

From a shell, using the archicad-gdl command:

archicad-gdl build chair.3ds --name "My Chair" --config assets.json
archicad-gdl deploy "build/My Chair.gsm" --place 0 0 --preview check.png

The command line tool comes with the uv tool install paths above and not with the Claude Desktop extension, which bundles an interpreter for its own use rather than putting anything on your PATH.

Tools

QA (both modes): list_instances, get_model_summary, list_rules, run_rule, audit_delivery_readiness, verify_ifc_export_readiness, highlight_failures, create_issues_from_failures, save_project

save_project is File > Save behind a confirm=true, for the moment before a property read that could crash Archicad. A refused save is explained: a project made in an older Archicad needs File > Save As once (an Archicad 27 file in Archicad 28 was refused this way), as does one never saved, and the tool does no Save As itself. file_updated says whether the file on disk changed. On a Teamwork project it saves your local copy and sends nothing; that is Graphisoft's documented behaviour of File > Save in Teamwork, not tried live here. In verdicts mode it leaves the project name and location out of its answer. highlight_failures zooms to the failures as well as highlighting them, and a rule with no failures removes the highlight.

Core (full mode): find_elements, search_definitions, get_element_data, set_element_data, create_elements, create_swept_beam, create_road_marking, modify_elements, apply_favorites, move_elements, delete_elements, get_selection, set_selection, clear_selection, show_elements, find_collisions, get_project_info, list_attributes, edit_attributes, list_issues, create_issue, add_issue_comment, attach_elements_to_issue, export_issues_bcf, import_issues_bcf, export_ifc, publish, read_schedule_scheme, edit_schedule_scheme, validate_schedule_scheme. Every write is dry-run by default; delete and move also require confirm=true. A tool that needs a newer Tapir than the one installed refuses before sending anything, naming the version it needs and the one it found. No other Archicad MCP server does this: Graphisoft's own writes on the first call, so an agent pointed at a live project has no rehearsal step there.

create_elements places any of the 34 element types Tapir can create: walls, beams, columns, slabs, roofs, morphs, meshes, stairs, railings, zones, objects, lamps, doors and windows in walls, openings, MEP routes and elements, sections, interior elevations, hotlink instances, 2D lines to texts and labels, keynote labels, dimensions (associative, wall thickness, on a section) and drawings on a layout. Items use Tapir's own fields; items=[] returns a type's item schema. The dry run validates every item, checks that a named favourite exists, and checks hosts (a door's wall, the elements a dimension measures) for existence, type and editability, so an item that would fail is skipped with its reason instead of sent. Model elements are placed from the floor plan or the 3D window; 2D elements go into whichever drawing window is active.

find_elements is a criteria query in the shape of Archicad's Find & Select: groups of property comparisons, AND or OR within a group, OR between groups, an element-type filter per group, 22 operators including string matching, classification branch tests and the four senses of "empty". search_definitions is the discovery step before it: fuzzy, accent-insensitive search over property and attribute definitions that returns the exact property address the other tools accept and whether the value can be written. Both are documented in the query guide.

modify_elements changes elements that already exist: story, layer and draw order for any element, and for walls, beams, slabs, columns, doors, windows, morphs, multi-plane roofs, meshes, objects, lamps, texts and labels the fields of Tapir's own Modify command (height, thickness, sill height, sizes, attributes by name). The dry run shows the current value next to the new one for every element. A story change moves the element with the story, as Archicad does; keep_elevation relinks it in place. Elements Archicad would refuse (hidden or locked layer, hotlinked module, locked, not reserved) are named and skipped, never unlocked. A commit reads the elements back, so a field Archicad answered success for but did not change shows up under not_applied. Needs Tapir 1.5.9 or newer.

apply_favorites makes existing elements match an office favourite, the way the Favorites palette does: "make these 40 doors Internal Door". Without a favourite it lists the ones that fit the elements' types. The dry run lists what it would change and skips elements of another type or ones Archicad would refuse. It also warns what a favourite takes over besides materials and pens, because Tapir's "never geometry" is not what Archicad does: live, a wall took the favourite's height, top link, reference line and layer, and doors and windows their library part, size and sill; plan positions stayed. For the types not checked live the dry run says so. Each element keeps its own Element ID by default (keep, which can also keep the layer), since a favourite's ID is a template value. A commit reads the elements back and reports, per element, every field that changed. Classifications, categories and property values are applied but not read back. to_defaults=true sets a tool's defaults instead. Needs Tapir 1.5.7.

get_element_data and set_element_data read and write more than property values, through one address syntax: classification:<System> for an element's classification item, gdl:<name> for a GDL parameter of an object, lamp, door or window, marker:<name> for a door's or window's marker parameter (the door number on many office stamps), and ifc:<Pset>.<Name> for a local IFC property. One call can mix them with properties. The dry run shows current and new for every change and names the ones it would skip; a commit sends classifications first and reads everything back, so a GDL value a Parameter Script replaced shows up under not_applied. Lengths are in metres and angles in radians throughout; the tool converts where Tapir takes degrees. IFC writes work only in Archicad 27 and older, where Tapir supports them. See Reading and writing element data.

show_elements is how an agent points at something. It finds the view that holds the elements: the floor plan with their story, or a section, elevation, detail, worksheet or layout (found through the Navigator, one database at a time). It opens that story or view, selects the elements, highlights them and zooms to them. Archicad answers success for selections and zooms it did not make, so the selection is read back (selected, not_selectable) and the story or window is checked after the switch. Elements on other stories or in other views are listed for another call. With the 3D window in front it stays in 3D, unless some are 2D elements (labels, dimensions, texts) that 3D does not draw. guids=[] removes the highlight and the selection. It changes only what is on screen. Needs Tapir 1.3.1; the story switch needs Tapir 1.7.0, and with an older Tapir the result says which story to open by hand.

find_collisions is a clash check between two groups of elements, or within one: each group is GUIDs (from find_elements, say) plus every element of the given types. It returns the colliding pairs with both elements' type and ID, counts by type pair, and every element involved, ready for show_elements. The volume tolerance (m3) ignores small overlaps; a surface tolerance (m2) also reports touching faces and open surfaces. Archicad leaves out what its own junctions clean up, such as crossing walls, and building materials set not to take part in collision detection, so an empty answer is not proof that nothing overlaps. Clashes can also be a QA rule, no-collisions (see Rules). Needs Tapir 1.5.7; the rule needs only 1.2.2.

export_ifc is the step after verify_ifc_export_readiness: it saves the project as .ifc or .ifczip with an export translator chosen by name (the preview translator by default) and one of Archicad's five element scopes. The dry run shows the translator, the path, the scope and every translator the project has. It never replaces an existing file without overwrite=true, and after the export it checks that the file is there. Archicad exports only from the floor plan or the 3D window, so from another window it brings the floor plan to the front first. It never opens or merges IFC. Needs Tapir 1.6.0.

edit_attributes creates, changes and deletes attributes (layers, layer combinations, lines, fills, zone categories, pen tables, profiles, building materials, composites, surfaces) and sets their property values. Tapir's attribute commands create or overwrite, and an overwrite quietly drops what it is not sent (a composite's wall/slab/roof availability, for one). So a create never replaces an existing attribute (the dry run shows what would change and the modify to send instead), a modify names the attribute and keeps every field it does not change, and values Tapir would silently replace with a default (a misspelt line type, an unknown building material) are refused before anything is sent. A layer is deleted only when no element is on it, since Archicad deletes a layer's elements with it. Fields reference other attributes by name; list_attributes(details=true) shows current settings in the same form. Attribute writes cannot be undone in Archicad. Needs Tapir 1.5.4 or newer.

Teamwork (full mode): reserve_elements, release_elements. Both are confirm-gated. A dry run reports what can be known without touching the server: unknown GUIDs and elements already in your workspace. Who holds the rest is only learned by attempting, because Archicad exposes no read for it; with confirm=true the result separates reserved, reserved by others (with the user's name), already mine, not found, and indirectly reserved. Verified live: reserving one door also pulled in its wall and the wall's other door, and the tool reported both. Sending and receiving stay in the gateway. Needs Tapir. Both also take object_sets, the non-element things Teamwork reserves: an attribute type (Layers, Composites, Fills, ...), Properties / Classifications, or any Archicad set name (Favorites, ProjectInfo, ...). For sets the dry run does say who holds them. Releasing a set sends its changes to the server, as Archicad does. In a Teamwork project the definition tools and edit_attributes refuse an edit whose set is not reserved (or a teammate holds) and name the exact call to reserve it, before anything is sent. Needs Tapir 1.7.1. The set names come from the Archicad DevKit, except ClassificationsAndProperties (properties and classifications), which Archicad carries but does not document; all of them answered on the CVP Teamwork project (read only). Reserving, releasing and the refusal without a reservation have not been tried on a Teamwork project yet.

Definitions (full mode): edit_property_definitions, edit_classifications, import_definitions. They edit property definitions and classification systems in place, instead of exporting XML from Property Manager or Classification Manager, editing it and importing it back. A property can be renamed, moved to another group, given a new default or expressions, made available for a classification branch (System/Code/*), and have its enum options renamed, removed, added or reordered. Classification items take a new code, name or description. Everything keeps its GUID, so values and classifications on elements survive, except where you remove an enum option (those elements show <Undefined>) or availability. All three are dry-run by default. They need a Tapir add-on that has UpdateClassificationItems (Tapir 1.6.0 or newer); with an older Tapir they refuse plainly and send nothing.

Setup (full mode): install_tapir, the tool form of archicad-mcp install-tapir (see Install Tapir). Dry run by default, confirm=true to write, replace_existing=true to replace a Tapir that is already there.

Gateway (full mode): list_api_commands, describe_api_command, execute_read_api_command, execute_write_api_command. The complete official + Tapir command surface (343 commands with the 1.7.1 definitions), for anything the curated tools don't cover.

Library parts (full mode): list_gdl_sources, inspect_gdl_source, build_gdl_object, deploy_gdl_object. Turn mesh models (OBJ, 3DS) into placeable Archicad library parts with finish variants, without opening the GDL editor. Requires the GDL workspace folder to be set and added as a linked library in Archicad once. See the GDL pipeline guide.

Scripting (opt-in, full mode): run_script, apply_changeset. run_script runs a short Python script next to Archicad and returns only what it returns; its writes are planned into a changeset instead of sent. apply_changeset writes that changeset after confirm=true and reads the values back. Off by default: enable with --enable-scripts, ARCHICAD_MCP_SCRIPTS=1, or Enable scripts in the extension settings. There is no sandbox. See Scripting.

Reads and writes are separate tools throughout, and every tool declares whether it is read-only or destructive. Clients use those declarations to decide what to run without asking you: a read never prompts, a write always does. The gateway splits the command catalog the same way, 149 reads and 194 writes, classified by command name with anything unrecognised treated as a write. The write half also refuses to run without confirm=true, because it can reach DeleteElements and QuitArchicad.

Development

uv sync && uv run pytest          # offline suite

To install unreleased main rather than a release, point uv at the repository instead of at a wheel, or append a tag to build a released version from source:

uv tool install git+https://github.com/alesdev88/Archicad-MCP.git          # main
uv tool install git+https://github.com/alesdev88/[email protected]   # a release

Live tests need a running Archicad. Open a small, non-sensitive test model and pin the port explicitly. Never run these against a client or teamwork project, and re-read the crash warning above first:

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

After a Tapir add-on update, refresh the bundled command schemas:

uv run python scripts/sync_tapir_defs.py

To move the installer to another Tapir release, pin it (this writes the sizes and sha256 hashes GitHub publishes for every add-on asset), review the diff, and check the new version live before releasing:

uv run python scripts/pin_tapir_release.py 1.7.1

Build the Claude Desktop extensions. One bundle per platform, both from this one machine (Node is needed, for the mcpb packer):

uv run python scripts/build_bundle.py --target all

Each bundle gets a relocatable CPython from python-build-standalone with every locked dependency installed into its own site-packages, so it starts with no uv, no system Python and no network. The tree contains compiled wheels, which is why a bundle is platform-specific; the build is not, because uv pip install --python-platform resolves wheels for a named target. Source builds are refused outright: one would compile for this machine and put the result in a bundle labelled for another, which fails at import on the user's machine with nothing to explain why.

That refusal is also why there is no Intel macOS bundle. The script self-tests the bundle it just built whenever the target is the machine building it, and says so when it cannot, which is every time you cross-build for Windows.

The version is written in four places (pyproject.toml, manifest.json, server.json, and the download links in this README) and the test suite fails if they drift:

uv run python scripts/check_release_version.py

Releasing is a tag push. .github/workflows/publish.yml refuses the tag unless all four files and the tag itself agree, then builds both bundles, the wheel and the sdist, installs that wheel without uv.lock and starts it (a fresh install resolves the newest dependencies the version ranges allow, which the locked tests never see), attaches them to a GitHub release, publishes the wheel and sdist to PyPI as archicad-mcp-server, stamps each bundle's SHA-256 into server.json, and publishes that to the MCP registry. Run the check by hand first, because a pushed tag has to be deleted before it can be corrected, and both PyPI and the registry refuse a version they already hold:

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

A cross-built Windows bundle cannot be executed by the machine that built it, so install one on Windows before trusting a release. The 0.2.1 bundle was checked that way and runs. Each new release should be tested on Windows before being used in production.

icon.png is rasterised from icon.svg, so the mark stays editable as vector art: change the SVG, then redraw the PNG the bundle ships. Pillow does that rasterising. It used to be pulled in just for this step, but the GDL pipeline now needs it to downscale textures, so it is a project dependency and the script can use it directly:

uv run python scripts/make_icon.py

Docs

• Known issues: the property-read crash, the element ceiling, verified property names, and what is validated end-to-end.
• Writing rules: every rule type, field, and the scoring model.
• Reading and writing element data: the addresses get_element_data and set_element_data take, units, and the readback.
• Schedule criteria codes: the empirical Param_Type and Relation_Index table, and how to extend it.
• GDL pipeline: mesh models to library parts with finish dropdowns, and the GDL fine print the generator encodes.
• Scripting: run_script and apply_changeset, the ac object a script sees, and the trust model behind the opt-in switch.
• API dashboard: every one of the 343 reachable commands, grouped, showing which have a dedicated tool and which are gateway-only. Generated rather than written; refresh it with uv run python scripts/build_dashboard.py after a Tapir definitions sync, and the push publishes it.

Privacy Policy

The server runs entirely on your machine and makes no outbound network connections. It talks to the Archicad JSON API on 127.0.0.1, ports 19723 to 19743, and to nothing else. There is no telemetry, no analytics, and no backend: the author receives nothing, including error reports.

Model data the server reads is returned to the MCP client that asked for it, normally Claude Desktop, which sends it to Anthropic as part of your conversation under Anthropic's Privacy Policy. Nothing is cached or retained by the server between requests. Two reductions are built in: verdicts mode keeps the project name out of what the model sees, and Teamwork credentials are stripped from every tool's reply before it returns.

Full text: PRIVACY.md.

License

MIT. See LICENSE.