ETABS MCP

_{由实时 ETABS 23 会话渲染：每个构件、挠度和 D/C 比都是真实数据。MP4}

etabs-mcp

让你的 AI Agent 进入 ETABS。

面向 CSI ETABS v22+ 的智能体 Model Context Protocol 服务。Claude Code、Codex、Factory Droid、Cursor 及任何 其他 MCP 客户端，都可以通过官方 ETABS API，像工程师一样对结构进行建模、加载、分析、设计和检查， 且每次调用都会根据真实签名进行校验。

快速开始 · 工具 · 工作原理 · 测试 · 配置

为什么选择它

ETABS 拥有庞大的自动化 API：143 个接口、1,293 个可调用方法、58 个枚举。它还充斥着 ref 数组、状态码和不易察觉的特殊行为。Agent 应该专注于设计建筑，而不是纠结于 COM 编组。

etabs-mcp 为 Agent 提供两个层次：

亮点

快速开始

**要求：**Windows · ETABS 22 或更高版本（需授权）· Python 3.10+ · .NET 8 Desktop Runtime（随 ETABS 22+ 安装）。

从 PyPI 安装：

pip install etabs-mcp

或者使用 uv 运行，无需安装：

uvx etabs-mcp --list-installs

**Claude Desktop，一键安装：**根据你的 Python 版本，从最新版本下载 etabs-mcp-<version>-py3XX.mcpb 并打开。Claude Desktop 会安装扩展，并包含所有依赖项。

检查是否能找到 ETABS：

etabs-mcp --list-installs

连接你的 Agent

claude mcp add etabs -- etabs-mcp

[mcp_servers.etabs]
command = "etabs-mcp"
tool_timeout_sec = 600

{
  "mcpServers": {
    "etabs": {
      "command": "etabs-mcp",
      "env": { "ETABS_MCP_CONNECT_MODE": "auto" }
    }
  }
}

etabs-mcp --transport streamable-http --port 8765

然后直接提出要求：

“建立一个 2 层钢框架，2×1 跨，每跨 6 m × 5 m，柱采用 W14X90，梁采用 W18X35，楼板厚 200 mm。 施加 1.5 kPa SDL 和 3 kPa 活荷载，运行分析，报告 T₁、风致侧移和最不利钢构件 D/C 比，并展示 3D 视图。”

服务会自动连接：连接到正在运行的 ETABS，或启动一个实例。

71 个工具

此外还有 资源（etabs://api/interfaces、etabs://api/interface/{name}、etabs://api/enum/{name}、 etabs://server/info）以及一个 提示词（etabs_build_and_check），引导 Agent 完成整个工作流。

// 1. find it
etabs_search_api({ "query": "frame releases" })
// → SapModel.FrameObj.SetReleases(Name, ref II[], ref JJ[], ref StartValue[], ref EndValue[], ItemType)

// 2. call it: plain JSON, validated and converted to the exact .NET types
etabs_call_api({
  "path": "FrameObj.SetReleases",
  "args": { "Name": "13", "II": [false,false,false,false,false,true],
            "JJ": [false,false,false,false,false,true],
            "StartValue": [0,0,0,0,0,0], "EndValue": [0,0,0,0,0,0] }
})
// → { "ok": true, "ret": 0, "outputs": { ... } }

Agent 看到的内容

上方影片截取自一次录制的会话。Agent 通过 etabs-mcp 建立了一栋 6 层、4×3 跨的支撑钢结构建筑， 对其进行分析并运行 AISC 360-16 检查，发现 48 根梁超限，于是增大它们的截面，并反复重新运行所有步骤，直到没有构件超出承载力。

建模 · 354 根构件、72 块楼板、30 次工具调用	设计 · 48 根构件超限，最大 D/C 为 1.22	迭代 · W24X76 × 48 → 0 根构件超限，最大 D/C 为 0.91

etabs_render_view

Agent 根据模型数据绘制的专属视图。即使 ETABS 隐藏，它也能正常工作，不会占用焦点，并能显示 ETABS API 无法切换 GUI 显示的内容。

color_by="design_ratio"	deformed_case="EQX", color_by="displacement"	color_by="section", theme="light"

_{Agent 使用 etabs_screenshot 捕获的同一模型在 ETABS 中的画面。}

工作原理

flowchart LR
    A["AI agent<br/>Claude Code · Codex · Droid · Cursor"] -- "MCP (stdio / HTTP)" --> S

    subgraph S["etabs-mcp"]
        direction TB
        T["71 curated tools<br/>+ generic dispatcher"] --> P["Policy<br/>read-only · confirm · blocked"]
        P --> C["Coercion<br/>JSON → typed args, ByRef placeholders"]
        C --> K["API catalog<br/>live reflection of ETABSv1.dll"]
        K --> W["Single STA worker thread"]
    end

    W -- "pythonnet / CoreCLR<br/>MethodInfo.Invoke" --> D["ETABSv1.dll<br/>(the installed version)"]
    D -- "COM, cross-process" --> E["ETABS.exe"]
    E -. "screen capture" .-> A

**对 API 进行逆向工程，而非对 ETABS 进行逆向工程。**此服务始终使用官方文档说明的 OAPI，不会修补或反编译 ETABS 引擎。其 API 范围根据随附的互操作程序集梳理而成：

1. REA 对 ETABSv1.dll 进行静态元数据分析：365 个类型、3,275 个方法定义、14,752 个参数。
2. 反射转储工具（tools/ApiDump）会将每个公共接口、签名、ByRef 标志、默认值和枚举写入 etabs_api_spec.json。
3. **交叉核对：**反射结果与原始元数据完全一致（例如，cFrameObj + cAnalysisResults + cDatabaseTables = 136 个方法 + 1 个属性访问器 = REA 的 137 个）。
4. 运行时，服务会重新反射已加载的 DLL，因此验证结果始终与所运行的 ETABS 相符。

让一切“开箱即用”的工程细节：

• **类型化封送。**pythonnet 会将 Python int 在 object[] 中装箱为 PyInt，而反射无法将其用于 Int32。每个参数都会通过一个单元素类型化数组和 Array.Copy 进行传递，因此 ETABS 收到的是实际的 Int32/Double/枚举装箱对象和 ByRef 数组。
• **单线程。**ETABS 和 COM 代理并非线程安全；所有调用都会在单个工作线程上串行执行。
• 连接丢失（ETABS 已关闭或崩溃）会通过 HRESULT 检测到，并提示重新连接。
• 处理 ETABS 的特殊情况：
  • 检测并还原 ETABS 静默重命名的库导入项（W14X90 → W14X90-1）。
  • 编辑表格后，ETABS 会将模型文件报告为临时文件 .$et；保存时会映射回 .EDB。
  • 无单位的结果列（漂移比、质量比）会转换为数值，而 Label: "1" 这样的 ID 会保留为字符串。
  • GPU 绘制的视口在 PrintWindow 中显示为空白，因此截图会从合成后的屏幕获取，之后焦点会交还给原窗口。

经真实 ETABS 测试

离线（CI）： 58 项测试。每个精选工具都会通过 FastMCP 对接一个模拟后端运行，该后端会针对真实的 ETABSv1.dll 目录解析并校验每次调用的参数类型。方法名或参数名错误时，会像在 ETABS 中一样失败。

实时端到端测试： tests/live/test_live_e2e.py 会将服务作为真实的 MCP 子进程启动，运行 ETABS 23.3.2，并在约 42 秒内执行 42 次工具调用，0 次失败：

实时 v0.2 测试套件： tests/live/test_live_v2.py 会在一个 3 层、63 个构件的模型中，针对 ETABS 驱动每个新增工具：

实时 v0.3 测试套件： tests/live/test_live_v3.py：

演示运行（tools/record_demo_data.py）：一个 6 层钢支撑建筑，包含 354 个构件和 72 块楼板。LL ΣFz = 9,720 kN（= 3 kPa × 30 m × 18 m × 6 层，完全一致），风荷载 ΣFx = 432 kN（= 18 kN × 24 个节点，完全一致），T₁ = 1.71 s。重新设计循环将最大 D/C 从 1.22 降至 0.91。

pip install -e ".[dev]"
pytest                                   # offline suite
ETABS_MCP_ARTIFACTS=docs/live pytest tests/live --live -s   # drives your local ETABS

配置

发布（维护者）

标记 vX.Y.Z 会运行 release.yml，执行测试、构建 wheel、sdist 和 .mcpb 包，并发布 GitHub 版本。PyPI 和 MCP Registry 使用无需令牌的可信发布： 在 pypi.org 添加可信发布者（此仓库、工作流 release.yml、环境 pypi），然后设置 仓库变量 PUBLISH_PYPI=true。之后的标签会发布到 PyPI，并在 MCP Registry 中列出此服务。

版本支持

安全模型

通过 etabs_menu 执行的菜单命令也需要 confirm=true，并且通过 HTTP 发送的每个请求都必须携带 Bearer 令牌。

项目结构

src/etabs_mcp/
  server.py        FastMCP assembly: tools, resources, prompt, agent instructions
  session.py       connection lifecycle + single worker thread + generic call()
  dotnet.py        pythonnet host, live reflection, typed marshalling, connection-loss detection
  catalog.py       API catalog: path resolution, search, describe
  coerce.py        JSON → signature-typed values, results → JSON
  policy.py        read / write / destructive / blocked classification
  discovery.py     ETABS installs and running instances
  screenshot.py    window capture
  render.py        offscreen model renderer (etabs_render_view)
  units.py         unit-aware lengths ("6 m", "20 ft", "250 mm")
  gui.py           ETABS menu commands through Windows UI Automation
  http.py          HTTP transports with bearer-token auth
  tools/           curated tools (connection, model, generator, geometry, properties, loads, lateral,
                   analysis, concrete, checks, tables, view, insight, api)
mcpb/              Claude Desktop extension manifest    server.json   MCP Registry entry
  data/etabs_api_spec.json   reflected API of ETABSv1.dll
tools/ApiDump                .NET reflection dumper that produced the API spec
tools/record_demo_data.py    drives the MCP tools against live ETABS and records the showcase data
tools/render_hero.py         renders the README film and stills from that data
tools/build_mcpb.py          builds the Claude Desktop extensions
tests/             offline suite + live end-to-end test

故障排除

• install_not_found：运行 etabs-mcp --list-installs；如果 ETABS 安装在特殊位置，请设置 ETABS_MCP_INSTALL_DIR。
• 连接后没有任何反应：等待 ETABS 完成启动并关闭所有模态对话框；或者向 etabs_connect 传入 pid。
• 分析后无法编辑：模型已锁定。etabs_unlock_model(confirm=true) 会删除结果并解锁模型。
• 长时间分析在客户端超时：提高客户端的 MCP 工具超时时间（参见连接你的 Agent）。
• 切换 ETABS 主版本：重启服务；一个进程只托管一个 ETABSv1.dll。