Archicad MCP

Un servidor MCP para Archicad 29 en macOS y Windows. Conecta Claude Desktop, Claude Code o cualquier cliente MCP a una instancia de Archicad en ejecución y hace dos trabajos:

1. QA de preparación para entrega. Los estándares de tu oficina, escritos como reglas YAML y ejecutados contra el modelo abierto. Devuelve aprobado/fallido, una puntuación y los GUID de los elementos que fallaron.

2. Acceso completo a la API. Herramientas seleccionadas para consultar, editar y crear elementos, además de una puerta de enlace a todos los comandos oficiales de la API JSON y de Tapir.

[!WARNING] Guarda antes de leer propiedades. GetPropertyValuesOfElements puede bloquear Archicad 29, incluso para una sola propiedad en un solo elemento, llevándose consigo el trabajo no guardado. Es un fallo del lado de Archicad que el servidor puede desencadenar pero no puede evitar. Afecta a audit_delivery_readiness, run_rule, get_element_data y set_element_data. Consulta Problemas conocidos antes de apuntar esto a un modelo que te importe.

Requisitos

• Archicad 29, en ejecución, con un proyecto abierto. La API JSON habla con la aplicación en vivo.

• uv, que instala el servidor y obtiene un Python adecuado (3.12+) para ti.

• Complemento Tapir, opcional pero recomendado. Necesario para la creación de elementos, problemas, comprobaciones IFC, resaltado y publicación; verificado en Tapir 1.5.3. Sin él, esas herramientas se degradan en lugar de dar error.

Related MCP server: redraft

Instalar como extensión de Claude Desktop (recomendado)

Un archivo, un clic, sin editar JSON. Descarga archicad-mcp-0.1.0.mcpb de la última versión y luego en Claude Desktop abre Configuración > Extensiones y arrástralo.

El modo, la carpeta de reglas de la oficina y el límite de lectura de propiedades aparecen entonces como campos de formulario en la configuración de la extensión, y todo el servidor tiene un interruptor de encendido/apagado. Deja un campo vacío y se usará el valor predeterminado de la tabla siguiente.

Aún necesitas uv en la máquina: la extensión lo usa para construir su propio entorno en el primer lanzamiento, lo que tarda unos segundos la primera vez y es instantáneo después.

Si prefieres configurarlo manualmente, o estás en Claude Code, usa una de las secciones siguientes. Esas instalan la rueda desde una versión etiquetada, así que obtienes una versión conocida en lugar de lo que sea que tenga main. Para actualizar, vuelve a ejecutar el comando de instalación con la URL de la versión más reciente desde la página de versiones.

Instalar en macOS

# 1. Install uv (skip if you already have it)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Install the server from the latest release
uv tool install https://github.com/alesdev88/Archicad-MCP/releases/download/v0.1.0/archicad_mcp-0.1.0-py3-none-any.whl

# 3. Note the path (you need it for the config below)
which archicad-mcp        # ~/.local/bin/archicad-mcp

Edita ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "archicad": {
      "command": "/Users/YOU/.local/bin/archicad-mcp",
      "args": ["--mode", "full"],
      "env": { "ARCHICAD_MCP_RULES_DIR": "/Users/YOU/office-rules" }
    }
  }
}

Usa la ruta absoluta. Claude Desktop no hereda el PATH de tu shell, así que un "archicad-mcp" desnudo suele fallar al iniciarse. Reinicia Claude Desktop después de editar el archivo.

Instalar en Windows

# 1. Install uv (skip if you already have it)
winget install --id=astral-sh.uv -e

# 2. Install the server from the latest release
uv tool install https://github.com/alesdev88/Archicad-MCP/releases/download/v0.1.0/archicad_mcp-0.1.0-py3-none-any.whl

# 3. Note the path (you need it for the config below)
where.exe archicad-mcp    # %USERPROFILE%\.local\bin\archicad-mcp.exe

Edita %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "archicad": {
      "command": "C:\\Users\\YOU\\.local\\bin\\archicad-mcp.exe",
      "args": ["--mode", "full"],
      "env": { "ARCHICAD_MCP_RULES_DIR": "C:\\Users\\YOU\\office-rules" }
    }
  }
}

Las barras invertidas deben duplicarse en JSON, y la extensión .exe importa. Reinicia Claude Desktop después de editar el archivo.

Instalar para Claude Code

Claude Code hereda el PATH de tu shell, así que el nombre de comando desnudo funciona:

uv tool install https://github.com/alesdev88/Archicad-MCP/releases/download/v0.1.0/archicad_mcp-0.1.0-py3-none-any.whl
claude mcp add archicad -- archicad-mcp --mode full

Comprobar que funciona

Con Archicad abierto, pide al cliente que liste las instancias de Archicad. La herramienta list_instances informa del puerto, la versión, el proyecto abierto y si Tapir respondió, que es la forma más rápida de distinguir un problema de configuración de un problema de conexión. Si no se encuentra nada, consulta Problemas conocidos: conexión.

Si el cliente no muestra ninguna herramienta, el servidor nunca se inició, y preguntarle cualquier cosa no te dirá por qué. Lee el registro en su lugar. El servidor escribe lo que encuentra en stderr al inicio, que Claude Desktop captura:

tail -20 ~/Library/Logs/Claude/mcp-server-archicad.log   # %APPDATA%\Claude\logs on Windows

archicad-mcp: mode=full, 12 rules loaded
archicad-mcp: Archicad 29 (build 4006) on port 19723, project 'Sample', Tapir 1.5.3

Esa línea distingue los tres fallos que parecen idénticos desde la ventana de chat: el servidor no se inicia (sin línea alguna), Archicad no está en ejecución (la línea lo dice, y dice que las herramientas se conectan bajo demanda una vez que lo inicies), y falta el complemento Tapir (la línea nombra qué herramientas se degradan).

Configuración

Modos

Reglas

Apunta ARCHICAD_MCP_RULES_DIR (o --rules-dir) a un directorio de archivos YAML:

- id: walls-fire-rating
  type: property-required
  property: "OFFICE/Fire Rating"   # user properties are "Group/Name"
  applies_to: { element_type: Wall }
  severity: error
  tags: [ifc-delivery]

Cinco tipos de regla vienen integrados (property-required, classification-required, layer-compliance, zone-number-required, ifc-property-required), y las comprobaciones personalizadas van en un custom_rules.py junto al YAML. Sin un directorio de reglas, se cargan los ejemplos incluidos para que tengas algo que ejecutar.

Mantén los estándares reales de la oficina fuera de este repositorio, en un directorio de reglas local.

Referencia completa: docs/rules.md.

Programaciones

Archicad no expone ninguna API para programaciones. Ni la API JSON, ni Tapir, y según Graphisoft tampoco la API C++. Lo que sí soporta es el viaje de ida y vuelta XML integrado en la Configuración de esquemas, y es a través de eso que funcionan estas herramientas:

1. En Archicad: Documento > Programaciones > Configuración de esquemas, selecciona un esquema, Exportar

2. Edítalo: read_schedule_scheme para ver qué hace, edit_schedule_scheme para aplicar una especificación YAML, validate_schedule_scheme para comprobar sus enlaces contra el proyecto abierto

3. En Archicad: Configuración de esquemas > Importar

Una especificación de esquema se ve así:

- id: door-schedule
  template: exports/door-scheme.xml
  name: "Door Schedule"
  columns:
    - caption: "Quantity"
      bind: { builtin: Quantity }
    - caption: "Fire Resistance"
      bind: { gdl_param: "Fire Rating" }
      width: 40

Una columna se enlaza de tres maneras:

• bind: { property: "<GUID>" }, que no necesita conexión con Archicad, o una cadena "Grupo/Nombre", que edit_schedule_scheme resuelve conectándose a Archicad y buscando el nombre. Una especificación que solo usa GUID (más los enlaces gdl_param y builtin, más abajo) se ejecuta completamente sin conexión; una especificación con incluso una propiedad nombrada necesita Archicad abierto con el proyecto que la define.

• bind: { gdl_param: "<nombre de parámetro>" }, un parámetro de parte de biblioteca por nombre

• bind: { builtin: Quantity } para los pocos integrados nombrados, o bind: { builtin: { param_type: 0, param_index: -1561 } } para cualquier otro integrado por sus números brutos

La tabla nombrada contiene deliberadamente solo Quantity: los códigos detrás de ella no están documentados y se están mapeando empíricamente, un ejemplo confirmado a la vez. La forma de números brutos es lo que permite que un esquema se exprese completamente incluso cuando un integrado aún no tiene nombre, y esto no es un caso raro: en una programación de puertas real de 27 columnas, 2 columnas lo necesitan.

Una columna también puede llevar width: <número>, que ajusta su ancho de celda para que coincida. Esto es una operación nula, informada como tal, cuando la columna ya tiene ese ancho. Solo se garantiza el ancho vertical: el campo de ancho horizontal también se actualiza cuando una columna ya tiene uno, pero nunca se crea en una columna que carece de él, ya que no se ha confirmado que sea un campo que Archicad mismo escriba para cada esquema, y el registro de cambios lo dice claramente en lugar de adivinar.

Los criterios se leen y se conservan, pero aún no se pueden editar: los códigos numéricos detrás de ellos no están documentados y se están mapeando en docs/scheme-criteria-codes.md.

Limitaciones

• Los criterios se leen y se conservan, pero aún no se pueden editar. Consulta docs/scheme-criteria-codes.md para ver qué se ha confirmado sobre los códigos detrás de ellos hasta ahora, y qué sigue siendo desconocido.

• Cada edición requiere dos pasos manuales en Archicad, Exportar antes e Importar después, porque ninguna API llega a las programaciones.

• Aún no se ha confirmado si reimportar un esquema editado lo actualiza en su lugar o crea un duplicado numerado. La documentación de Graphisoft dice que los nombres duplicados se numeran automáticamente, pero las exportaciones reales llevan IDs de esquema estables, lo que sugiere que puede ser posible una coincidencia en el lugar. Prueba en un proyecto de prueba antes de confiar en cualquiera de los comportamientos.

• edit_schedule_scheme rechaza cualquier archivo que no sobreviviera a un guardado sin cambios. Esto protege las partes del formato que el servidor no modela.

Herramientas

QA (ambos modos): list_instances, get_model_summary, list_rules, run_rule, audit_delivery_readiness, verify_ifc_export_readiness, highlight_failures, create_issues_from_failures

Núcleo (modo completo): query_elements, get_element_data, set_element_data, create_elements, move_elements, delete_elements, manage_selection, get_project_info, list_attributes, manage_issues, publish, read_schedule_scheme, edit_schedule_scheme, validate_schedule_scheme. Cada escritura es de prueba por defecto; eliminar y mover también requieren confirm=true.

Puerta de enlace (modo completo): list_api_commands, describe_api_command, execute_api_command. La superficie completa de comandos oficiales + Tapir (231 comandos en la configuración verificada), para cualquier cosa que las herramientas seleccionadas no cubran.

Desarrollo

uv sync && uv run pytest          # offline suite

Para instalar main sin publicar en lugar de una versión, apunta uv al repositorio en lugar de a una rueda, o añade una etiqueta para construir una versión publicada desde el código fuente:

uv tool install git+https://github.com/alesdev88/Archicad-MCP.git          # main
uv tool install git+https://github.com/alesdev88/Archicad-MCP.git@v0.1.0   # a release

Las pruebas en vivo necesitan un Archicad en ejecución. Abre un modelo de prueba pequeño y no sensible y fija el puerto explícitamente. Nunca ejecutes estas contra un proyecto de cliente o de trabajo en equipo, y vuelve a leer la advertencia de bloqueo anterior primero:

ARCHICAD_MCP_LIVE_PORT=<port> uv run pytest -m live -v

Después de una actualización del complemento Tapir, actualiza los esquemas de comandos incluidos:

uv run python scripts/sync_tapir_defs.py

Construye la extensión de Claude Desktop. version en manifest.json y en pyproject.toml deben indicar lo mismo, y la suite de pruebas falla si se desvían:

uv run python scripts/check_release_version.py
npx @anthropic-ai/mcpb validate manifest.json && npx @anthropic-ai/mcpb pack . dist/archicad-mcp-0.1.0.mcpb

.mcpbignore decide qué se incluye. El paquete lleva pyproject.toml y uv.lock en lugar de ruedas empaquetadas, así que uv resuelve el mismo conjunto de dependencias fijadas en la máquina de destino y un solo paquete sirve tanto para macOS como para Windows.

Publicar es un push de etiqueta. .github/workflows/release.yml rechaza la etiqueta a menos que ambos archivos y la propia etiqueta coincidan en la versión, luego construye el paquete, la rueda y el sdist y adjunta los tres a una versión de GitHub. Ejecuta la misma comprobación manualmente primero, porque una etiqueta que se ha empujado debe eliminarse antes de poder corregirse:

uv run python scripts/check_release_version.py v0.1.1
git tag v0.1.1 && git push origin v0.1.1

icon.png se genera, no se dibuja a mano, así que permanece editable. Pillow solo se necesita para redibujarlo y deliberadamente no es una dependencia del proyecto:

uv run --with pillow python scripts/make_icon.py

Documentación

• Problemas conocidos: el fallo de lectura de propiedades, el límite de elementos, los nombres de propiedades verificados y lo que se valida de extremo a extremo.

• Reglas de escritura: cada tipo de regla, campo y el modelo de puntuación.

• Códigos de criterios de programación: la tabla empírica de Param_Type y Relation_Index, y cómo ampliarla.

Licencia

MIT. Ver LICENSE.