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

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.

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

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