Skip to main content
Glama
tapir-archicad-mcp

tapir-archicad-mcp

by SzamosiMate

Archicad Tapir MCP Server

Connect your AI assistant to Archicad. Use natural language to explore projects and automate workflows through the Tapir add-on and the official Archicad JSON API.

PyPI version CI Platforms: Windows and macOS Supported Tapir version License: MIT

See it in action

Astra uses photos and a plan as references to model in Archicad.

Watch the Archicad modeling demo on YouTube

Related MCP server: archicad-mcp

What can it do?

  • Inspect open projects, elements, properties, and attributes.

  • Find elements that match conditions on type, properties, and classifications.

  • Create and modify model elements, and work with views and layouts.

  • Export project data and use supported IFC and Teamwork commands.

  • Access 800+ Archicad commands, discovered on demand by your assistant.

  • Connect to multiple running Archicad instances.

Quick start

Before installing the MCP server, make sure Archicad is running on Windows or macOS and install these two requirements:

  1. Tapir add-on — an Archicad add-on that gives the server access to Archicad's automation commands. Install it in Archicad for the version you use.

  2. uv — a tool that installs and runs the MCP server and its dependencies. Install it on the computer running Archicad.

You'll also need an MCP client: the AI application that connects to the server.

Ask your AI to install it

Copy this prompt into your AI assistant:

Install the Archicad Tapir MCP server for my MCP client, following the instructions at https://github.com/SzamosiMate/tapir-archicad-MCP/blob/master/docs/setup-and-configuration.md. Help me verify that it can connect to my running Archicad instance.

Install it yourself

If your client supports MCP bundles, download tapir-archicad.mcpb and open it in your client. The client must be able to find uv on its PATH.

Prefer the old-school approach? Follow the manual setup instructions—editing a config file is optional hacker cred.

Try it

With Archicad running, ask your assistant:

What Archicad projects do I have open?

The assistant can list ready instances, their project names and ports, and report instances that are unavailable. If you have multiple projects open, specify the port when asking it to work on one.

How it works

Your MCP client runs this server, which connects to Archicad through multiconn_archicad. The server exposes five MCP tools for finding instances, searching and browsing commands, looking up their schemas, executing commands, and checking long-running jobs. Your assistant can search for several workflow steps at once and narrow results by command group.

Important to know

The server can create, modify, and delete model elements, export files, and interact with Teamwork. Project names, paths, and model data returned by commands are sent to your MCP client. Review changes made to your projects and use a copy when experimenting.

Available commands depend on your installed Archicad and Tapir versions. Instance discovery reports a missing Tapir add-on as unavailable and warns when the installed Tapir version differs from the version supported by the server.

Documentation

See Setup and configuration for client setup, troubleshooting, server options, HTTP transports, jobs, and pagination.

See Command discovery for keyword search, follow-up searches, and benchmarks.

See Element queries for finding and filtering elements.

Development and contributing

To develop the server, clone the repository and run uv sync from the project directory. Then configure your MCP client to run the Python interpreter from that checkout's virtual environment:

Client setting

Windows

macOS

Command

<project>\.venv\Scripts\python.exe

<project>/.venv/bin/python

Arguments

-m, tapir_archicad_mcp.server

-m, tapir_archicad_mcp.server

Replace <project> with the absolute path to your checkout. This runs the local code instead of the published uvx package. Restart the server in your client after making changes. Run tests with uv run pytest tests.

Generated commands

The Archicad command wrappers in src/tapir_archicad_mcp/tools/generated/ are generated from the exact multiconn-archicad version pinned in pyproject.toml. The generator reads command metadata from that release's Git tag; scripts/generator_config.py controls naming, exclusions, pagination, and image handling, and scripts/generate_tools.py produces the wrappers. To change generated behavior, review the generator and its configuration rather than only editing the generated files, since regeneration can overwrite those edits.

Contributions

Ideas, bug fixes, and small, focused improvements are welcome. For larger features, architectural changes, or major rewrites, please open an issue to discuss the approach before investing in a pull request. I may prefer to work through those changes myself as part of understanding and shaping the design.

AI-assisted contributions are welcome. Please keep pull request descriptions short and in plain language: explain the problem, your solution, and how you checked it. For larger changes in particular, understand the proposed implementation and be ready to discuss the design and trade-offs.

License and acknowledgments

This project is licensed under the MIT License. The bundle icon uses the Tapir mark from ENZYME-APD/tapir-archicad-automation (branding/logo/png/tapir_logo_black_512.png), MIT, Copyright 2024 Enzyme APD.

Available Tools

5 tools
archicad_call_toolExecute Archicad API CommandA
Destructive

Executes a specific Archicad API command by its 'name'. CRITICAL WORKFLOW: You MUST use 'archicad_get_command_schema' first to understand the exact JSON structure required for the 'arguments' parameter. The 'arguments' dictionary MUST contain a 'port' number (obtained from 'discovery_list_active_archicads'). If a tool's response includes a 'next_page_token', call this same tool again with the same parameters and add a 'page_token' key to the 'arguments' dictionary. Long executions return status='running' and a jobHandle; retrieve them with archicad_get_job. If a response is lost or cancelled, list jobs with archicad_get_job() before retrying a write. Cancelling this request does not cancel an admitted execution.

Inputs: name (required), arguments (required).

archicad_get_command_schemaGet Archicad Command SchemaA
Read-onlyIdempotent

Retrieves the exact JSON schema (required arguments) for a specific Archicad command. Provide the exact 'command_name' obtained from 'archicad_list_commands'. CRITICAL: You MUST call this tool before executing 'archicad_call_tool' to ensure you provide the correct parameters. Do NOT guess or hallucinate parameters based on the command name.

Inputs: command_name (required). Returns: The detailed JSON schema required to execute a specific Archicad command.

archicad_get_jobGet or List Archicad JobsA
Read-onlyIdempotent

With no job_handle, immediately lists all retained executions newest first, including fast, completed, and failed jobs, with command, port, timestamps, and a short argumentsPreview. Use this to recover after a lost response before retrying a write; similar calls may be ambiguous. With a job_handle, waits up to the configured threshold and returns running, completed with result, or failed with error. Polling never redispatches commands.

Inputs: job_handle.

archicad_list_commandsList Available Archicad CommandsA
Read-onlyIdempotent

Search by keyword phrases or exact command names. Batch separate workflow steps and narrow by groups as needed.

For every follow-up on the same user request, pass the latest query_id from the previous response, even when replacing all keywords or changing groups. Omit query_id to start a new task or restart an unavailable chain.

The matches list returns up to 12 pooled ranked command names with descriptions. An exact name in scope returns that name and its status in exact_matches by keyword_index. Omit keywords to browse names.

Available groups: analytical, app, attributes, classifications, components, custom_data, design_options, dev, elements, favorites, grouping, ifc, issues, keynotes, layout, library, mep, navigator, project, project_data, properties, revisions, solid_ops, teamwork, view. Use archicad_get_command_schema before executing a selected command.

Inputs: groups, keywords, query_id. Returns: result

discovery_list_active_archicadsList Active Archicad InstancesA
Read-onlyIdempotent

Scans for and lists running Archicad instances. Returns 'active' (ready to receive commands with their target 'port') and 'unavailable' (instances that are unresponsive or missing the Tapir Add-On).

Inputs: no named parameters. Returns: The result of scanning for Archicad instances.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool occupies a distinct step in a clearly prescribed workflow: discover instances, search commands, fetch a schema, execute, and poll jobs. The descriptions explicitly state prerequisites and boundaries, leaving no realistic chance of misselection.

    Naming Consistency4/5

    Four tools share the archicad_ prefix with a verb_noun pattern (list_commands, get_command_schema, get_job, call_tool), but discovery_list_active_archicads uses a different prefix and the generic 'call_tool' noun is vaguer than its peers.

    Tool Count5/5

    Five meta-tools is exactly the right scope for a proxy that exposes hundreds of underlying Archicad commands via dynamic search and schema lookup. Each tool is load-bearing; nothing is redundant.

    Completeness4/5

    The surface covers discovery, search, introspection, execution, pagination, and job retrieval, which is solid lifecycle coverage. Minor gaps exist: no way to cancel or delete jobs despite mentions of cancellation, and no batching/parallel execution helper.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP server for Archicad automation, enabling AI assistants to run Python scripts against running Archicad instances via the Tapir JSON API for complex workflows.
      4
      202 PyPI
      8
      MIT
    • F
      license
      A
      quality
      B
      maintenance
      Read-only MCP bridge for Archicad using the Tapir Add-On, enabling discovery, context binding, and safe read operations on Archicad projects.
      8
      -
    • A
      license
      C
      quality
      B
      maintenance
      Enables Claude and other MCP clients to query and modify an open Archicad project through Graphisoft's official JSON API and the ~250 commands of the Tapir add-on, covering model summaries, quantity takeoffs, quality checks, element creation (walls, slabs, zones), ID management, undo/journal history, and execution of arbitrary API or Tapir commands.
      53
      1
      MIT