Archicad

CI PyPI

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:

{
  "mcpServers": {
    "archicad": {
      "command": "uvx",
      "args": ["archicad-mcp"]
    }
  }
}

Save the configuration and restart or reload the client. Then call:

get_docs(command="API.GetAllElements")

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:

get_docs()
get_docs(search="create slab")
get_docs(command="API.GetAllElements")
get_docs(commands=["API.GetAllElements", "CreateSlabs"])

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.

result = await archicad.command("GetProductInfo")

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:

uv tool install archicad-mcp

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.

Variable	Behavior
ARCHICAD_MCP_AUTO_UPDATE=0	Disable automatic schema checks while retaining a valid cache.
ARCHICAD_MCP_OFFLINE=1	Disable schema-update network access while retaining a valid cache.

Offline schema mode does not stop uvx from acquiring the package. Use archicad-mcp schemas status, archicad-mcp schemas update, and archicad-mcp schemas reset to inspect, update, or reset the cache. An older installed Tapir add-on may not implement commands in a newer active schema; built-in Archicad documentation is unaffected.

See Schema snapshots and updates for the cache, validation, update, and maintainer contracts.

Contributing and releases

See CONTRIBUTING.md for development setup and checks, report bugs with the GitHub bug form, and find release notes and artifacts on GitHub Releases.

License

MIT