Archicad-MCP

# 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](https://github.com/ENZYME-APD/tapir-archicad-automation) 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](docs/known-issues.md) 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](https://docs.astral.sh/uv/)**, which fetches a suitable Python
  (3.12+) for you.
- **[Tapir add-on](https://github.com/ENZYME-APD/tapir-archicad-automation/releases)**,
  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](https://github.com/alesdev88/Archicad-MCP/releases/latest):

| Platform | File |
|---|---|
| Windows | `archicad-mcp-0.8.0-win32.mcpb` |
| macOS (Apple silicon) | `archicad-mcp-0.8.0-darwin-arm64.mcpb` |

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

```bash
# 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.8.0/archicad_mcp_server-0.8.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`:

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

```powershell
# 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.8.0/archicad_mcp_server-0.8.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`:

```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:

```bash
uv tool install archicad-mcp-server
# or pin this exact release instead:
# uv tool install https://github.com/alesdev88/Archicad-MCP/releases/download/v0.8.0/archicad_mcp_server-0.8.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](#development).

```bash
# 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](#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:

```bash
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](docs/known-issues.md#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:

```bash
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

| Flag | Env var | Default | What it does |
|---|---|---|---|
| `--mode` | `ARCHICAD_MCP_MODE` | `full` | `full` or `verdicts` (see below) |
| `--rules-dir` | `ARCHICAD_MCP_RULES_DIR` | bundled examples | Directory of YAML rule files |
| `--port` | n/a | auto-detect `19723`-`19743` | Pin when several Archicads run at once |
| `--transport` | `ARCHICAD_MCP_TRANSPORT` | `stdio` | `stdio` for Claude Desktop, Claude Code, Codex; `http` (Streamable HTTP at `/mcp`) for ChatGPT and other remote clients |
| `--host` | n/a | `127.0.0.1` | Bind address, `--transpor