convez.ai
MCP ServerAutomaçãoAvançado
Boti-Ormandi

Archicad MCP Server

Boti-Ormandi/archicad-mcp

Automação de Archicad via scripts Python com IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que conecta assistentes de IA ao Archicad via API Tapir JSON, permitindo automação de projetos arquitetônicos através de scripts Python. Oferece descoberta multi-instância, busca full-text em 173 comandos Archicad e execução assíncrona com acesso completo à API.

Instalação

$npx convez-ai Boti-Ormandi/archicad-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
8
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
v0.2.2
Issues abertas
11
Contribuidores
2

Casos de uso

  • Gerar cronogramas de áreas e propriedades de elementos arquitetônicos
  • Consultar e modificar múltiplas instâncias Archicad simultaneamente
  • Executar fluxos complexos de automação CAD com lógica Python nativa

Veredito

Ferramenta robusta para arquitetos e desenvolvedores que precisam integrar IA com Archicad em nível enterprise. A arquitetura script-first e documentação dinâmica eliminam overhead de wrappers por comando, mas exige familiaridade com Python async e Tapir API.

README

A tradução para o português deste README ainda está na fila.

archicad-mcp

CI PyPI Python License: MIT Code style: ruff

MCP server for Archicad automation. Connects AI assistants to running Archicad instances via the Tapir JSON API, enabling everything from simple queries to complex multi-step workflows through Python scripting.

Built on a script-first architecture: 4 MCP tools front 173 underlying Archicad commands (100 Tapir + 73 built-in). Rather than expose each command as its own tool, the server lets the AI write Python directly against the API.

Design

Minimal tool surface. Every Archicad command is accessible through execute_script, which provides full async Python with loops, filtering, and file I/O. Complex logic lives in Python scripts, not in per-command tool wrappers.

Dynamic documentation. The execute_script tool description is generated at startup from live Archicad schemas. The AI always sees accurate command signatures, parameter types, and examples - no stale docs.

Multi-instance. Parallel port scanning across 19723-19744 discovers all running Archicad instances. Target any instance by port number - work with multiple projects simultaneously.

Full-text search. Inverted index over all command schemas with weighted field scoring and fuzzy matching via rapidfuzz. Typo-tolerant: "proprty" still finds property commands.

Tools

ToolPurpose
list_instancesDiscover running Archicad instances (port, project name, version, Tapir status)
execute_scriptExecute Python with full async Archicad API access and file I/O
get_docsSearch and retrieve command documentation (schemas, examples, parameters)
get_propertiesDiscover element properties (area, volume, length) with cached GUID lookup

Example

A typical interaction — "give me a room area schedule by floor":

The AI calls list_instances to find a running Archicad:

[
  {
    "port": 19723,
    "project_name": "Residential_Block.pln",
    "project_path": "C:/Projects/Residential_Block.pln",
    "project_type": "solo",
    "archicad_version": "27.0.0",
    "is_tapir_available": true
  }
]

Then get_properties to look up the GUID for "Net Area":

{
  "found": true,
  "property": {
    "name": "Net Area",
    "group": "Zone",
    "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "StaticBuiltIn",
    "value_type": "Real",
    "measure_type": "Area",
    "editable": false
  }
}

Then execute_script with the Python it composes from those lookups:

zones = (await archicad.tapir("GetElementsByType", {"elementType": "Zone"}))["elements"]
details = (await archicad.tapir("GetDetailsOfElements", {"elements": zones}))["detailsOfElements"]
# guid from the get_properties response above
props = (await archicad.tapir("GetPropertyValuesOfElements", {
    "elements": zones,
    "properties": [{"propertyId": {"guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}}],
}))["propertyValuesForElements"]

by_floor: dict = {}
for zone, det, row in zip(zones, details, props):
    floor = det["floorIndex"]
    raw_area = row["propertyValues"][0]["propertyValue"]["value"]
    # Locale: Archicad may return "12,40" instead of "12.40"
    area = float(str(raw_area).replace(",", "."))
    bucket = by_floor.setdefault(floor, {"zones": [], "total_m2": 0.0})
    bucket["zones"].append({"name": det["details"]["name"], "area_m2": round(area, 2)})
    bucket["total_m2"] = round(bucket["total_m2"] + area, 2)

result = {"total_zones": len(zones), "by_floor": by_floor}

Returns:

{
  "success": true,
  "result": {
    "total_zones": 18,
    "by_floor": {
      "0": {
        "zones": [
          {"name": "Entrance Hall", "area_m2": 8.4},
          {"name": "Living Room", "area_m2": 32.1}
        ],
        "total_m2": 55.2
      },
      "1": {
        "zones": [
          {"name": "Master Bedroom", "area_m2": 22.3}
        ],
        "total_m2": 37.1
      }
    }
  },
  "execution_time_ms": 287
}

A per-command MCP server would chain those API calls into separate tool invocations and force the AI to aggregate client-side. With execute_script, the chain, the loop, and the aggregation all live in one round-trip.

Quick Start

Install the Tapir add-on into your Archicad (versions 25–29 supported, Windows and macOS). It ships as a per-version .apx (Windows) or .zip (macOS) file, installed via Archicad's Options → Add-On Manager → Add.

Then add to your MCP client configuration (e.g. Claude Desktop, VS Code, etc.):

{
  "mcpServers": {
    "archicad": {
      "type": "stdio",
      "command": "uvx",
      "args": ["archicad-mcp"]
    }
  }
}

uvx fetches the latest release from PyPI on first run. Pin to a specific version like ["archicad-mcp@0.1.0"]. To run from a local checkout instead, see Development.

Use

With Archicad running, the server auto-discovers instances on startup. Ask your AI assistant to interact with Archicad — it has full access to the command reference and can write scripts for complex operations.

Security

The script executor supports two security modes, controlled via environment variables:

VariableValuesDefault
ARCHICAD_MCP_SECURITYunrestricted, sandboxedunrestricted
ARCHICAD_MCP_BLOCKED_PATHSComma-separated glob patternsOS system directories
ARCHICAD_MCP_ALLOWED_WRITE_PATHSComma-separated glob patternsDesktop, Documents, temp

Unrestricted (default): Read/write access to most paths. System directories (e.g. C:/Windows, /usr) are always blocked.

Sandboxed: Read access everywhere, write access restricted to the allowed paths list.

Requirements

  • Python 3.11+
  • Archicad 25–29 with the Tapir add-on installed
  • An MCP-compatible client

Development

git clone https://github.com/Boti-Ormandi/archicad-mcp.git
cd archicad-mcp
uv sync --all-extras   # runtime + dev tooling (ruff, mypy, pytest)

To point your MCP client at the local checkout instead of the published package:

{
  "mcpServers": {
    "archicad": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/archicad-mcp", "archicad-mcp"]
    }
  }
}

Dev tooling:

# Lint and format
ruff check src/
ruff format src/

# Type check
mypy src/

# Tests (unit + mock, no Archicad needed)
pytest -m "not integration"

# Integration tests (requires running Archicad)
pytest

Schema sync

The repo uses git submodules in deps/ for upstream schema tracking (CI-only, not needed for local development). To regenerate the embedded schemas locally:

git submodule update --init
archicad-mcp-sync deps/tapir       # regenerates src/archicad_mcp/schemas/tapir.json
archicad-mcp-sync deps/multiconn   # regenerates src/archicad_mcp/schemas/builtin.json

License

MIT

Ver o original no GitHub

Bom para

Relacionados