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. 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. Required for element creation, issues, IFC checks, highlighting, and publishing. The bundled command definitions are synced from Tapir 1.5.8, and the server has been exercised live against 1.5.9, so a newer add-on than the definitions is fine. Without the add-on, those tools 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 wheel from a tagged release, so you get a known version rather than whatever main happens to be. To upgrade, re-run the install command with the newer version's URL from the releases page.

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 the latest release
uv tool install https://github.com/alesdev88/Archicad-MCP/releases/download/v0.5.2/archicad_mcp-0.5.2-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 the latest release
uv tool install https://github.com/alesdev88/Archicad-MCP/releases/download/v0.5.2/archicad_mcp-0.5.2-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 https://github.com/alesdev88/Archicad-MCP/releases/download/v0.5.2/archicad_mcp-0.5.2-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

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. 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).

Configuration

Modes