The emergence of archicad-mcp on PyPI marks a significant step forward for professionals seeking to automate Graphisoft Archicad workflows without the overhead of complex plugin development. By implementing the Model Context Protocol (MCP) over standard input/output, this lightweight server offers a programmable interface that can be invoked from any MCP‑compatible client, ranging from custom scripts to AI‑driven agents. What sets this release apart is its focus on delivering a stable, versioned contract between the client and Archicad’s capabilities, ensuring that automation scripts remain reliable even as the underlying CAD environment evolves. For BIM managers and computational designers, the promise of being able to query, discover, and execute Archicad functions through a consistent API opens the door to more sophisticated generative design pipelines, automated documentation checks, and real‑time model validation.
At the heart of archicad-mcp lies the native MCP SDK, which chooses stdio as its transport mechanism deliberately. This decision avoids the complexities of network ports, firewalls, or authentication handshakes that often plague SOAP or REST‑based integrations in corporate environments. By communicating through standard streams, the server can be launched directly from a terminal, containerized in Docker, or spawned as a child process by an orchestrator, all while maintaining a predictable, low‑latency channel. The stdio approach also simplifies debugging; developers can tap into stdin/stdout logs to trace request/response payloads without setting up proxies or inspecting network traffic. For teams already invested in MCP‑based tooling for other platforms, adding Archicad to the mix becomes a matter of pointing the client to a new executable rather than learning a completely new integration paradigm.
Rather than flooding the client with hundreds of individual commands—one for every native Archicad API call—the archicad-mcp server exposes just four high‑level tools: list_instances, get_docs, get_properties, and execute_script. This minimal surface area reduces the cognitive load on API consumers and encourages a workflow where discovery precedes action. list_instances scans the local machine for running Archicad processes, giving the client a handle to the target session. get_docs serves as a searchable catalog of available capabilities, pulling from an immutable registry that reflects the true set of functions exposed by the Tapir add‑on and the native API. get_properties lets users interrogate element attributes, while execute_script provides a sandboxed Python environment for orchestrating multi‑step operations. By concentrating power in these four endpoints, the server promotes a clean separation between metadata inquiry and actual model manipulation.
One of the most innovative aspects of archicad-mcp is its reliance on immutable, packaged snapshots of the command library—builtin.json for core Archicad functions and tapir.json for Tapir‑specific operations. These files are bundled with the PyPI release and represent a fixed point‑in‑time view of the documentation generated by the Tapir add‑on’s own GenerateDocumentation utility. Because the snapshots are immutable, clients can start browsing and searching the full command catalog immediately, even if no Archicad instance is currently running. This capability is invaluable for IDE autocomplete, documentation generation, or pre‑flight validation of automation scripts. Moreover, each entry in the registry records the exact version of the Tapir add‑on that introduced or last modified the command, allowing developers to ascertain feature compatibility without guessing or trial‑and‑error.
Discovery and retrieval are designed to be deterministic and user‑friendly. A simple call to get_docs() returns the entire catalog, while get_docs(search=”…”) performs an intent‑based search across command names, descriptions, and tags. The system accepts both bare identifiers (e.g., CreateSlabs) and namespaced forms (tapir:CreateSlabs or native:API.GetAllElements), ensuring that clients can unambiguously reference a capability regardless of naming conventions. Batch retrieval is also supported, enabling users to fetch documentation for dozens of commands in a single round‑trip. This predictability eliminates guesswork when constructing automation pipelines and makes it feasible to generate dynamic user interfaces that adapt to the exact set of functions available in a given Archicad/Tapir combination.
The server’s approach to schema updates strikes a careful balance between staying current and guaranteeing stability. Upon startup, archicad-mcp performs a single, bounded, nonblocking check against the authoritative Tapir GitHub repository, but only if a shared 24‑hour time‑to‑live (TTL) permits. This means the server never blocks its launch waiting for network responses; it immediately serves the packaged or previously cached snapshot and proceeds with its work in the background. If the check succeeds and a newer, validated schema is found, the active view is swapped atomically; otherwise, the existing view remains untouched. Users retain fine‑grained control via environment variables: ARCHICAD_MCP_AUTO_UPDATE=0 disables the automatic check, ARCHICAD_MCP_OFFLINE=1 blocks all outbound network traffic while still allowing the cached schema to be loaded, and the archicad-mcp schemas update command triggers a manual refresh on demand.
Multi‑instance awareness is another practical consideration baked into the server. By default, archicad-mcp scans the local host for Archicad instances listening on TCP ports 19723 through 19743 inclusive, a range chosen to avoid collisions with other common services. Port 19744 is deliberately omitted from the scan, providing a clear boundary for administrators who might wish to reserve that port for alternative tools. This port‑based discovery enables the server to address multiple concurrent Archicad sessions—a common scenario in large firms where different teams may be working on separate project files simultaneously. The list_instances tool returns connection details for each discoverable instance, allowing the client to select a target explicitly or to iterate over all available sessions for batch processing.
When it comes to executing user‑supplied logic, the execute_script tool adopts an “honest local execution” model. The command spawns a disposable child process running under the same user account as the server, thereby inheriting the user’s file system, network, and process privileges. The child process is equipped with timeout and cancellation handling, and its standard output and error streams are captured and returned to the caller in a structured format. Importantly, this design does not attempt to provide hostile‑code isolation; scripts retain the same authority as any other program launched by the user. Consequently, organizations should enforce their own code‑review and approval policies before allowing arbitrary scripts to be run via execute_script, especially in environments where security or regulatory compliance is paramount.
Getting started with archicad-mcp is remarkably frictionless thanks to its compatibility with the uvx launcher. Users can invoke the server directly from the PyPI distribution without creating a virtual environment or managing dependencies: a simple uvx archicad-mcp command launches the stdio MCP server, and the explicit alias archicad-mcp serve does the same thing. For integration with existing MCP clients, the server provides a ready‑to‑copy configuration snippet via the archicad-mcp config subcommand, which outputs the necessary JSON‑style settings without modifying any files on disk. This read‑only approach ensures that administrators can inspect the effective runtime parameters—such as the active schema version, cache location, and update behavior—before committing them to a client’s configuration store.
The true power of archicad-mcp reveals itself when Tapir is present and matched to the Archicad major version in use. Installing a compatible Tapir add‑on unlocks the full suite of native plus Tapir capabilities, allowing the server to expose everything from parametric object creation to advanced geometry operations. If Archicad is reachable but Tapir is not installed or is incompatible, the server gracefully degrades to a tapir_unavailable mode. In this state, native API commands remain fully accessible via the get_docs and get_properties tools, while Tapir‑only entries are simply omitted from the capability view. This graceful degradation ensures that users can still benefit from automation—such as extracting element properties or issuing basic model queries—even when they have not yet adopted the Tapir ecosystem.
A typical automation session with archicad-mcp follows a clear, repeatable pattern. First, the client calls list_instances to identify one or more running Archicad processes and selects a target. Next, it employs get_docs (with or without a search term) or get_properties to gather the necessary identifiers, element handles, and command signatures required for the intended operation. Armed with this metadata, the client then invokes execute_script to run a Python workflow that may involve multiple steps: reading and modifying model data, performing calculations, generating reports, or triggering downstream processes. The default execution timeout of 300 seconds provides ample runway for complex tasks, while the ability to cancel via transport mechanisms ensures that runaway scripts can be reined in promptly. All stdout/stderr output is captured, making it straightforward to log results or surface errors to the user.
Looking ahead, the introduction of archicad-mcp signals a maturing ecosystem where BIM software is increasingly accessible through standardized, language‑agnostic protocols. For firms investing in AI‑assisted design, generative algorithms, or robotic process automation, having a reliable, version‑checked interface to Archicad reduces integration risk and accelerates experimentation. Practical advice for adopters includes: pinning the archicad-mcp version in your dependency manifest to avoid unexpected updates, leveraging the offline mode for secure or air‑gapped environments, and establishing internal governance around the execute_script tool to prevent unintended model changes. By treating the server as a trusted gateway rather than a free‑form conduit, organizations can harness the flexibility of script‑driven automation while maintaining the rigor and accountability essential to professional BIM delivery.