archicad-mcp

archicad-mcp is an MCP server for Graphisoft Archicad. It lets AI clients like Claude Desktop read and change an open Archicad project.

It uses the Tapir add-on and its JSON commands. Every Tapir command becomes one tool, built automatically from the Tapir command definitions. Nothing is written by hand per command.

Requirements

• Archicad 25 to 29
• The Tapir Archicad Add-On
• uv, a small tool that runs Python programs

Installation

1. Install Tapir

Download the add-on for your Archicad version from the Tapir releases page and follow the instructions there. This repository ships the definitions of Tapir 1.5.9.

2. Install uv

Follow the uv installation guide. One command, no other setup.

3. Add archicad-mcp to Claude Desktop

Open the Claude Desktop config file in a text editor:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Pick one of the two options below.

Option A: Quick install

Nothing to download. Paste this block into the config file. uvx comes with uv. On the first start it fetches the server and everything it needs, which can take a minute.

{
  "mcpServers": {
    "archicad-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/lgradisar/archicad-mcp", "archicad-mcp"]
    }
  }
}

Option B: From source

Use this if you want to read or change the code.

git clone https://github.com/lgradisar/archicad-mcp.git
cd archicad-mcp
uv sync

Then paste this block, with YOUR_DIRECTORY replaced by the full path to the archicad-mcp folder. On Windows write the path with forward slashes, for example C:/Users/you/archicad-mcp:

{
  "mcpServers": {
    "archicad-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "YOUR_DIRECTORY", "archicad-mcp"]
    }
  }
}

If Claude Desktop says it cannot find uvx or uv, write the full path to the program as command. Find it with where uvx on Windows or which uvx on macOS.

To update a quick install later, run uv cache clean archicad-mcp and restart Claude Desktop. To update a source install, run git pull and uv sync in the folder.

4. Restart Claude Desktop

Open a project in Archicad, then ask Claude to run TestConnection. It answers with the Archicad and Tapir versions. The tools are listed behind the tools icon in the chat box of Claude Desktop.

Settings

Settings are optional. They go into an "env" block in the config entry:

"env": { "ARCHICAD_MCP_MODE": "safe", "ARCHICAD_MCP_GROUPS": "project,element,property,navigator" }

Groups: application, project, element, element-grouping, favorites, property, classification, attribute, ifc, library, teamwork, navigator, issue-management, revision-management, design-options, keynote, mep, solid-element-operation, script-ui, developer.

Restart Claude Desktop after changing settings. If the tool list does not change, remove and re-add the server in the config.

Tools

• 250 Tapir commands, one tool each. See the Tapir command list. By default Claude finds them with search_tools and runs them with call_tool, so the full list never enters the conversation.
• TestConnection: reports the port, the Archicad version and the Tapir version.
• RunTapirCommand: runs any Tapir command by name. Useful when your Tapir is newer than the definitions shipped here. Only shown in all mode with no groups set.

Safety

• With ARCHICAD_MCP_SEARCH=0, Claude sees 252 tools. That is a lot of text for every conversation in Claude Desktop. Combine it with ARCHICAD_MCP_GROUPS or readonly mode, or leave search on.
• Some tools can do real damage: quit Archicad, open, close and save projects, delete things, send to Teamwork, publish, print, write files, change libraries, or show dialogs that block Archicad until someone clicks. ARCHICAD_MCP_MODE=safe hides all of them, plus RunTapirCommand.
• Claude Desktop asks before each tool runs. Approve tools one by one instead of allowing everything.
• Arguments are checked against the Tapir definitions before they are sent. Archicad checks them again.

Troubleshooting

• “Archicad is not running or the Tapir add-on is not loaded”: open a project in Archicad. If it is open, check that Tapir appears in the Add-On Manager.
• Several Archicad windows open: the first one that started answers. Set ARCHICAD_PORT to choose.
• Claude reports a timeout: Claude may stop waiting before Archicad finishes. Archicad keeps working. Publishing, library reload, drawing updates, Teamwork and IFC commands can take long. Check the result in Archicad before asking again.
• “is not available in the installed Tapir add-on”: your Tapir is older than the definitions shipped here. Update the add-on.
• Teamwork projects: changes need reserved elements. ReserveElements is a dangerous tool and hidden in safe mode.

Updating the Tapir definitions

When a new Tapir version comes out:

uv run scripts/update_tapir.py 1.5.9

Replace 1.5.9 with the new version. The script downloads the two definition files into src/archicad_mcp/tapir and prints how many commands it found. Check new commands against the lists in src/archicad_mcp/tools/classification.py.

Custom tools

You can add your own tools in src/archicad_mcp/tools/custom_tools.py. Use client.run_command for official Archicad JSON commands and client.run_tapir_command for Tapir commands. New Archicad commands are better contributed to Tapir directly.

License

MIT