Boti-Ormandi/archicad-mcp

archicad-mcp is a local stdio MCP server for Archicad automation through Archicad's built-in JSON API, with optional Tapir commands. Its four tool categories cover instance discovery, searchable command documentation, property discovery, and multi-step Python workflows. Validated Archicad and Tapir command documentation is packaged with the server and is available without a running Archicad instance.
Quick start
Requirements
- Python 3.11 or newer
- uv
- An MCP client that can launch a local stdio server
Add the server to the client's MCP configuration:
Save the configuration and restart or reload the client. Then call:
A successful response has the ID native:API.GetAllElements and includes the command schema. This first success requires neither Archicad nor Tapir.
Tools and workflow
| Tool | Purpose |
| --- | --- |
| list_instances | Find running Archicad instances and their ports. |
| get_docs | Browse, search, or retrieve built-in and Tapir command schemas. |
| get_properties | Find element properties and property IDs. |
| execute_script | Run a multi-step Python workflow against an instance. |
Use get_docs to move from discovery to exact schemas:
For live work, call list_instances, inspect the needed command schemas with get_docs and property IDs with get_properties, then pass the selected port to execute_script. Live tools require Archicad, and the server and Archicad must run on the same host. Tapir is needed only for Tapir calls and get_properties; built-in Archicad capabilities remain available without it.
Script execution
execute_script accepts the body of an async Python function. It injects archicad and port, permits top-level await, and returns the value assigned to result.
Scripts run as your operating-system user and are not sandboxed; review the code before executing it.
See Script execution for the complete authoring, result, cancellation, and safety contract.
Diagnostics and installation alternatives
Use the public console command for setup and diagnostics:
- uvx archicad-mcp setup prints the client-neutral configuration without editing files.
- uvx archicad-mcp doctor --json reports package, schema, and local Archicad diagnostics.
- uvx archicad-mcp config --json prints the effective runtime configuration.
- uvx archicad-mcp --version and uvx archicad-mcp --help report the installed version and available commands.
For a persistent installation, run:
The installed archicad-mcp command then replaces uvx archicad-mcp in terminal commands and the MCP configuration. If live discovery fails, check that Archicad is listening on its local JSON API port in the range 19723-19743.
For migration from 0.1.x, use the public console command; live schema generation, repository submodules, and a preliminary manual schema refresh are no longer part of command discovery.
Schema updates
get_docs uses the packaged command documentation or a newer validated Tapir snapshot from the user cache. When automatic updates are enabled and the shared 24-hour interval permits, startup schedules at most one bounded, nonblocking check. Startup does not wait for it, and there is no recurring timer or daemon.