Archicad

CI PyPI

archicad-mcp is an MCP server for Archicad automation through Archicad's built-in JSON API, with additional commands from the optional Tapir add-on. It exposes four MCP tools for instance discovery, command documentation, property discovery, and Python execution.

Command documentation is available without a running Archicad instance. The package includes validated Archicad and Tapir schema snapshots and can update the Tapir snapshot in the user cache without modifying the installed package.

Requirements

• Python 3.11 or newer
• An MCP client that supports stdio servers
• uv for the uvx commands below
• A running Archicad instance for live discovery and automation
• A Tapir release built for your Archicad major when using Tapir commands or get_properties

The project does not maintain a separate Archicad version matrix. Live compatibility depends on Archicad's JSON API and, for Tapir features, the add-on release installed for that Archicad major.

Quick start

Check the installation and local environment:

uvx archicad-mcp --version
uvx archicad-mcp doctor --json

Add the server to an MCP client configuration:

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

archicad-mcp with no arguments starts the stdio server. To print a ready-to-copy configuration without editing any files, run:

uvx archicad-mcp setup

MCP tools

Tool	Purpose	Runtime dependency
list_instances	Find running Archicad instances and report project, version, and Tapir availability.	Archicad
get_docs	Browse, search, or retrieve exact Archicad and Tapir command documentation.	None
get_properties	Find element properties and property identifiers for an instance.	Archicad and Tapir
execute_script	Run a Python workflow against a selected instance.	Archicad; Tapir only for Tapir calls

A typical discovery flow starts without Archicad:

get_docs()                                      # overview and categories
get_docs(search="create slab")                 # search by intent
get_docs(command="CreateSlabs")                # exact Tapir command
get_docs(command="API.GetAllElements")         # exact built-in command
get_docs(commands=["CreateSlabs", "API.GetAllElements"])

For live work, call list_instances, inspect command contracts with get_docs, obtain property identifiers with get_properties when needed, and then use execute_script for a multi-step workflow.

Compatibility and limitations

• Instance discovery scans local ports 19723 through 19743 inclusive.
• Without Tapir, a reachable instance is reported as tapir_unavailable; built-in Archicad commands remain available.
• get_docs reads the packaged or cached registry, not documentation generated by a live Archicad process.
• The active registry describes the current validated Tapir schema. An older installed add-on may not implement commands introduced later, and the server does not claim an exact historical schema for every older add-on release.
• Each Tapir command records the add-on version in which it was introduced or last changed.

Execution security

execute_script runs Python in a disposable child process under the same user account as the MCP server. The default timeout is 300 seconds, and a timeout or transport cancellation terminates the worker. The process boundary is not a sandbox. Scripts can access the user's files, imports, network, and processes, and can make destructive Archicad or Tapir changes. There is no approval or confirmation gate.

Schema updates

The packaged snapshots are sufficient for offline documentation discovery. By default, when a shared 24-hour interval permits, the server schedules at most one bounded, nonblocking startup check for a newer stable Tapir release. A validated update is written to the OS user cache and activated without modifying the installed package. The updater reads no GitHub token or other credential.

Variable	Behavior
ARCHICAD_MCP_AUTO_UPDATE=0	Disable automatic checks while continuing to use a valid cache.
ARCHICAD_MCP_OFFLINE=1	Forbid update network access while continuing to use a valid cache. Manual updates also refuse.

Manual controls are available through archicad-mcp schemas status, archicad-mcp schemas update, and archicad-mcp schemas reset. See Schema snapshots and updates for the trust, validation, cache, and maintainer contracts.

CLI reference

Command	Purpose
archicad-mcp	Start the stdio MCP server.
archicad-mcp serve	Start the same server explicitly.
archicad-mcp doctor --json	Report package, schema, and local Archicad diagnostics.
archicad-mcp setup	Print MCP client configuration.
archicad-mcp config --json	Print effective runtime settings.
archicad-mcp schemas status --json	Report local packaged, cache, active, and check state.
archicad-mcp schemas update --json	Request an immediate update check, subject to offline mode.
archicad-mcp schemas reset --json	Remove cached schema and check state.
archicad-mcp --version	Print the installed version.

Contributing

See CONTRIBUTING.md for development setup, checks, schema rules, and issue guidance.

Releases and migration

Release notes and artifacts are published on GitHub Releases. When migrating from 0.1.x, configure clients to launch the public uvx archicad-mcp console command rather than a package-internal server entry point; live schema generation, repository submodules, and a manual schema refresh are no longer required before command discovery.

License

MIT