# Archicad MCP by ArchBench

Connect an MCP-compatible assistant to Archicad using this independent, open-source connector. Basic connectivity is free and needs no ArchBench account.

**Status: experimental alpha.** Read the [validation record](docs/VALIDATION.md) before using it with real project files. Transport fixture tests are not native-application qualification.

Implementation target: **Archicad 26+ with its built-in JSON interface**. Node.js 22+ runs the MCP server. Install server dependencies with `npm ci --ignore-scripts`. No native package build or Python runtime is needed.

## Get the source

```sh
git clone https://github.com/3d-mcp/archicad-mcp.git
cd archicad-mcp
npm ci --ignore-scripts
```

The [alpha release](https://github.com/3d-mcp/archicad-mcp/releases/tag/v0.1.0-alpha.3) contains source downloads; Archicad uses its built-in JSON API. No npm registry release is included.

## Install the native connection

Open Archicad and a project. No additional host add-on or Tapir installation is required. The default JSON API port is 19723; set `ARCHICAD_MCP_PORT` in the MCP process environment to the intended instance port (19723–19743). The connector does not auto-select another open project.

## Connect your assistant

Configure the assistant to launch:

```sh
node /absolute/path/to/archicad-mcp/bin/archicad-mcp.mjs
```

[Codex, Claude Code and desktop JSON setup](docs/CLIENTS.md). The assistant must run on the same machine and as the same user as the native application.

## First request

“Check my Archicad connection, then describe the current selection.”

This calls `archicad_get_status` and `archicad_get_selection`. Native context is limited to basic document and selection information; it does not use an ArchBench workflow engine.

## Optional native access

Set `ARCHBENCH_MCP_ALLOW_SCRIPTS=1` in the MCP server environment to expose `archicad_call_command`. Calls accept `command`, `parameters`, and `confirm: true`.

Example native JSON API input:

```json
{
  "command": "API.GetSelectedElements",
  "parameters": {
    "onlyEditable": false
  },
  "confirm": true
}
```

Command availability is determined by the running Archicad version. The transport does not implement missing native modeling operations. It does not follow redirects, scan ports, or retry failed commands.

## ArchBench

Maintained by [ArchBench](https://archbench.com/?utm_source=archicad-mcp&utm_medium=readme&utm_campaign=open-source). Explore the separate product for integrated design work, project history, collaboration and workflows as those features become available. This connector remains usable independently.

This is an independent integration, not an official Archicad vendor project.

## Development and ownership

Run `npm run check` from this repository. It needs no sibling checkout or parent
workspace package. The checks use Node.js and a local HTTP fixture.

This is an independently implemented public connector for external MCP clients
such as Codex and Claude Code. For ArchBench its purpose is marketing and
distribution through useful connectivity and voluntary product discovery.
Neither this connector nor the proprietary product depends on the other.
ArchBench chat, mission graphs, IFC models/mappings, planners, reviewed execution,
history, collaboration and workflow engines remain in the separate product.
Do not share private source, contracts, protocols, credentials or runtime services.

[Architecture](docs/ARCHITECTURE.md) · [Release process](docs/RELEASING.md) · [Licensing](LICENSING.md)