Archicad MCP

一个用于 macOS 和 Windows 上的 Archicad 29 的 MCP 服务器。它将 Claude Desktop、Claude Code 或任何 MCP 客户端连接到正在运行的 Archicad 实例，并完成两项工作：

1. 交付就绪 QA。 你的办公室标准以 YAML 规则编写，并针对打开的模型运行。返回通过/失败、得分以及未通过元素的 GUID。

2. 完整 API 访问。 用于查询、编辑和创建元素的精选工具，以及通往所有官方 JSON API 和 Tapir 命令的网关。

[!WARNING] 读取属性前请先保存。 GetPropertyValuesOfElements 可能使 Archicad 29 崩溃，即使只是读取单个元素的单个属性，也会连同未保存的工作一起丢失。这是 Archicad 侧的故障，服务器可以触发但无法阻止。它影响 audit_delivery_readiness、run_rule、get_element_data 和 set_element_data。在将此工具指向你关心的模型之前，请参阅已知问题。

要求

• Archicad 29，正在运行，且已打开项目。JSON API 与实时应用通信。

• uv，用于安装服务器并为你获取合适的 Python（3.12+）。

• Tapir 插件，可选但推荐。创建元素、问题、IFC 检查、高亮和发布需要它；已在 Tapir 1.5.3 上验证。没有它，这些工具会降级而不是报错。

Related MCP server: redraft

安装为 Claude Desktop 扩展（推荐）

一个文件，一次点击，无需编辑 JSON。从最新发布下载 archicad-mcp-0.1.0.mcpb，然后在 Claude Desktop 中打开 设置 > 扩展 并将其拖入。

模式、办公室规则文件夹和属性读取上限随后会以表单字段的形式出现在扩展的设置中，整个服务器会有一个开关。将字段留空则回退到下表所示的默认值。

你仍然需要在机器上安装 uv：扩展在首次启动时使用它来构建自己的环境，第一次需要几秒钟，之后是即时的。

如果你更愿意手动配置，或者你使用的是 Claude Code，请改用以下各节。这些方式从带标签的发布版本安装 wheel，因此你获得的是已知版本，而不是 main 分支上的任意内容。要升级，请使用发布页面上较新版本的 URL 重新运行安装命令。

在 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

编辑 ~/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" }
    }
  }
}

使用绝对路径。Claude Desktop 不会继承你的 shell 的 PATH，因此裸的 "archicad-mcp" 通常无法启动。编辑文件后重启 Claude Desktop。

在 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

编辑 %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" }
    }
  }
}

JSON 中反斜杠必须双写，且 .exe 很重要。编辑文件后重启 Claude Desktop。

为 Claude Code 安装

Claude Code 会继承你的 shell 的 PATH，因此裸命令名即可工作：

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

检查是否正常工作

在 Archicad 打开的情况下，让客户端列出 Archicad 实例。list_instances 工具会报告端口、版本、打开的项目以及 Tapir 是否响应，这是区分配置问题和连接问题的最快方式。如果什么都找不到，请参阅已知问题：连接。

如果客户端完全没有显示任何工具，说明服务器从未启动，询问它任何问题都不会告诉你原因。请改读日志。服务器在启动时将发现的内容写入 stderr，Claude Desktop 会捕获这些内容：

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

这一行区分了在聊天窗口中看起来完全相同的三种故障：服务器未启动（完全没有行）、Archicad 未运行（该行会说明，并说明工具会在你启动它后按需连接）、以及 Tapir 插件缺失（该行会指出哪些工具会降级）。

配置

模式

规则

将 ARCHICAD_MCP_RULES_DIR（或 --rules-dir）指向一个 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]

内置五种规则类型（property-required、classification-required、layer-compliance、zone-number-required、ifc-property-required），自定义检查放在 YAML 旁边的 custom_rules.py 中。如果没有规则目录，则加载内置示例，这样你就有东西可以运行。

将真实的办公室标准放在此仓库之外，放在本地规则目录中。

完整参考：docs/rules.md。

明细表

Archicad 完全不提供明细表的 API。JSON API 没有，Tapir 没有，根据 Graphisoft 的说法，C++ API 也没有。它支持的是 Scheme Settings 中内置的 XML 往返，而这些工具正是通过这种方式工作的：

1. 在 Archicad 中：文档 > 明细表 > Scheme Settings，选择一个方案，导出

2. 编辑它：read_schedule_scheme 查看它的作用，edit_schedule_scheme 应用 YAML 规范，validate_schedule_scheme 检查其绑定是否与打开的项目匹配

3. 在 Archicad 中：Scheme Settings > 导入

方案规范如下所示：

- 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

列有三种绑定方式：

• bind: { property: "<GUID>" }，不需要连接 Archicad，或者使用 "Group/Name" 字符串，edit_schedule_scheme 通过连接 Archicad 并查找名称来解析它。仅使用 GUID（加上下面的 gdl_param 和 builtin 绑定）的规范可以完全离线运行；即使只有一个命名属性的规范也需要 Archicad 打开并加载定义该属性的项目。

• bind: { gdl_param: "<parameter name>" }，按名称引用库部件参数

• bind: { builtin: Quantity } 用于少数命名的内置项，或 bind: { builtin: { param_type: 0, param_index: -1561 } } 用于按原始数字引用任何其他内置项

命名的表特意只包含 Quantity：其背后的代码没有文档记录，正在逐个经验性地映射，一次一个已确认的示例。原始数字形式让方案即使在内置项还没有名称时也能完整表达，这不是罕见的边缘情况：在一个真实的 27 列门明细表上，有 2 列需要它。

列还可以携带 width: <number>，用于将单元格宽度设置为匹配值。当列已经具有该宽度时，这是一个空操作，并会如实报告。只保证纵向宽度：当列已有横向宽度字段时会更新它，但绝不会在缺少该字段的列上创建它，因为尚未确认 Archicad 本身是否为每个方案写入该字段，变更日志会明确说明而不是猜测。

条件会被读取并保留，但尚不可编辑：其背后的数字代码没有文档记录，正在 docs/scheme-criteria-codes.md 中映射。

限制

• 条件会被读取并保留，但尚不能编辑。 有关其背后代码目前已确认的内容以及仍未知的内容，请参阅 docs/scheme-criteria-codes.md。

• 每次编辑都需要在 Archicad 中手动执行两步，之前导出，之后导入，因为没有 API 可以触及明细表。

• 重新导入编辑过的方案是就地更新还是创建编号副本，尚未确认。 Graphisoft 的文档说重复名称会自动编号，但真实的导出带有稳定的方案 ID，这表明就地匹配可能是可能的。在依赖任一行为之前，先在草稿项目上测试。

• edit_schedule_scheme 拒绝任何无法在无操作保存后原样保留的文件。 这保护了服务器未建模的格式部分。

工具

QA（两种模式）： list_instances、get_model_summary、list_rules、run_rule、audit_delivery_readiness、verify_ifc_export_readiness、highlight_failures、create_issues_from_failures

核心（完整模式）： 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。默认情况下每次写入都是试运行；删除和移动还需要 confirm=true。

网关（完整模式）： list_api_commands、describe_api_command、execute_api_command。完整的官方 + Tapir 命令面（在已验证的设置上有 231 个命令），用于精选工具未覆盖的任何内容。

开发

uv sync && uv run pytest          # offline suite

要安装未发布的 main 而不是发布版本，请将 uv 指向仓库而不是 wheel，或者附加一个标签以从源码构建已发布版本：

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

实时测试需要正在运行的 Archicad。打开一个小的、非敏感的测试模型并显式固定端口。绝不要针对客户端或团队协作项目运行这些测试，并先重新阅读上面的崩溃警告：

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

在 Tapir 插件更新后，刷新内置的命令模式：

uv run python scripts/sync_tapir_defs.py

构建 Claude Desktop 扩展。manifest.json 中的 version 和 pyproject.toml 中的 version 必须一致，如果它们漂移，测试套件会失败：

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 决定打包什么。捆绑包携带 pyproject.toml 和 uv.lock 而不是内置的 wheel，因此 uv 在目标机器上解析相同的锁定依赖集，一个捆绑包同时适用于 macOS 和 Windows。

发布就是推送标签。.github/workflows/release.yml 会拒绝该标签，除非两个文件和标签本身在版本上一致，然后构建捆绑包、wheel 和 sdist，并将三者附加到 GitHub 发布。先手动运行同样的检查，因为已推送的标签必须先删除才能更正：

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

icon.png 是生成的，不是手绘的，因此它保持可编辑。Pillow 仅在重新绘制时需要，并且特意不是项目依赖：

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

文档

• 已知问题：属性读取崩溃、元素上限、已验证的属性名称，以及端到端验证的内容。

• 编写规则：每种规则类型、字段以及评分模型。

• 计划标准代码：经验性的 Param_Type 和 Relation_Index 表，以及如何扩展它。

许可证

MIT。参见 LICENSE。