An MCP server for automating Archicad through its built-in JSON API, with optional Tapir support, command/property discovery, and Python workflow execution.
list_instances: Scan ports 19723-19743 and return running Archicad instances with port, project, version, and Tapir availability.
get_docs: Browse, search, and retrieve full schemas for built-in Archicad and Tapir commands, even without a running Archicad instance.
get_properties: Discover element properties and GUIDs by keyword, element group, property type, measure type, or exact property lookup.
execute_script: Run async Python workflows against a selected Archicad port with top-level await, timeout control, stdout/stderr capture, and structured results.
CLI diagnostics & setup: Use commands like setup, doctor, config, and schemas status/update/reset for configuration and schema cache management.
Allows AI assistants to automate Archicad via Python scripting, enabling queries and complex multi-step workflows such as element property retrieval, zone area scheduling, and multi-instance project management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@archicad-mcp give me a room area schedule by floor"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Python 3.11 or newer
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.
Related MCP server: RevitMCPBridge2026
Tool | Purpose |
| Find running Archicad instances and their ports. |
| Browse, search, or retrieve built-in and Tapir command schemas. |
| Find element properties and property IDs. |
| 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.
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.
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-mcpThe 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.
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 |
| Disable automatic schema checks while retaining a valid cache. |
| 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.
See CONTRIBUTING.md for development setup and checks, report bugs with the GitHub bug form, and find release notes and artifacts on GitHub Releases.
Execute Python in a disposable same-account local_user worker against the selected Archicad port. This is reliability isolation only, not hostile-code isolation: scripts have ordinary local-user Python builtins and imports and can read or write files, start processes, or make destructive Archicad/Tapir changes with the user's authority. The default timeout is 300 seconds; any positive finite timeout is accepted and null disables it. Timeout or transport cancellation terminates the owned worker. Use get_docs to discover Archicad and Tapir commands.
Inputs: port (required), script (required), timeout_seconds. Returns: Result of same-account local-user script execution.
Get documentation for Archicad commands.
USAGE: get_docs() # Overview: categories with counts get_docs(category="Element Commands") # Browse: commands in a category get_docs(search="...") # Find commands by keyword get_docs(command="CommandName") # Full schema for one command get_docs(commands=["A", "B"]) # Full schemas for multiple
DISCOVERY WORKFLOW:
get_docs() -> see categories
get_docs(category="...") -> see command names
get_docs(command="...") -> full schema
SEARCH FEATURES:
Searches across: names, descriptions, parameters, examples, notes
Element types: "wall" -> suggests GetElementsByType(elementType="Wall")
Partial match: "prop" finds property commands
Typo tolerant: "proprty" -> property commands
Multi-word: "create slab" finds CreateSlabs
Args: search: Search query (e.g., "wall", "create slab", "property") command: Exact command name for full schema commands: List of command names for full schemas category: Category name to list all commands in it
Examples: get_docs() # Overview get_docs(category="Element Commands") # Browse category get_docs(search="wall") # Commands for walls get_docs(search="create") # Creation commands get_docs(command="CreateSlabs") # Full schema for CreateSlabs
Inputs: search, command, category, commands. Returns: object
Search and discover Archicad element properties.
Properties are attributes like area, length, volume that you query on elements. Use this to find property GUIDs needed for GetPropertyValuesOfElements.
WHEN TO USE:
"Get wall areas" → get_properties(search="area", group="Wall")
"What properties can I query on zones?" → get_properties(group="Zone")
"Find custom/user-defined properties" → get_properties(property_type="Custom")
MODES: get_properties(port) # Overview of all groups get_properties(port, search="length") # Search by keyword get_properties(port, group="Wall") # All properties for element type get_properties(port, property="Length of Reference Line") # Exact lookup
Args: port: Archicad instance port (from list_instances) search: Search property names (e.g., "area", "length", "surface") group: Filter by group/element type (e.g., "Wall", "Zone", "Geometry") property_type: Filter by type: "StaticBuiltIn", "DynamicBuiltIn", "Custom" measure_type: Filter by unit: "Length", "Area", "Volume", "Angle" property: Exact property name lookup (returns single match with GUID) limit: Max results (default 50, max 200)
Returns: Properties with GUIDs ready for GetPropertyValuesOfElements.
NOTE: For command documentation (API schemas), use get_docs instead.
Inputs: port (required), group, limit, search, +3 more. Returns: object
Find all running Archicad instances.
Scans ports 19723-19743 for Archicad's JSON API. Returns instance info including port, project name, version. Use the 'port' value in other tools to target a specific instance.
Inputs: no named parameters. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 4 tools
list_instances, get_docs, get_properties, and execute_script each target a distinct concern: instance discovery, command documentation, property metadata, and script execution. The only plausible confusion is between get_docs and get_properties since both are searchable catalogs, but their descriptions explicitly separate command schemas from element property GUIDs.
Tool names generally follow a verb_noun snake_case pattern (get_docs, get_properties, execute_script), but list_instances uses a different retrieval verb ('list' instead of 'get') and 'docs' is an abbreviation. These are minor deviations rather than a broken naming convention.
With four tools, the set is lean but not thin: each tool has a distinct role, and execute_script intentionally consolidates arbitrary Archicad command execution so dozens of per-command tools aren't needed. This is a well-scoped alternative to exposing every API function as a separate MCP tool.
The set covers the full workflow: discover an instance, learn available commands, look up property GUIDs, and execute arbitrary Python against the selected instance. Because execute_script can invoke any Archicad/Tapir command, there are no obvious CRUD/lifecycle dead ends within the domain.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
