ETABS MCP

io.github.Moha2005269由 GitHub 账号 Moha2005269 发布v0.3.2更新于 Nov 8, 2026

Agentic MCP server for CSI ETABS v22+: model, load, analyse, design and inspect structures.

已验证STDIO仅桌面开发者工具

概览

AI 生成的概览

让 AI 助手通过官方 ETABS API 驱动 CSI ETABS v22+，完成建模、加载、分析、设计与结构检查。

可以做什么
  • 管理 ETABS 会话：列出安装、连接、查看状态、断开，并可同时驱动多个实例。
  • 建模与编辑：楼层、轴网、框架、面对象、点、截面、材料、支座，并可一次调用生成整栋建筑。
  • 定义荷载与抗侧体系：荷载模式、组合、ASCE 7 地震与风荷载、反应谱、质量源、刚性隔板。
  • 运行分析与设计，读取结果、D/C 比、混凝土与剪力墙设计，以及层间位移、不规则性等规范检查。
  • 读写交互式数据库表格，渲染或截取视图，导出 .e2k 模型与 Markdown 设计报告。
  • 用纯 JSON 搜索、描述并调用约 1,300 个 ETABS API 方法，支持批量调用。
适用场景
适合在 Windows 上已安装正版 ETABS 的环境中，让助手生成并迭代建筑模型、运行分析与规范校核，或把原本在图形界面里手工完成的重复性 ETABS 工作自动化。
运行要求
Windows 桌面环境，已安装并授权的 ETABS 22 或更新版本，Python 3.10+ 与 .NET 8 Desktop Runtime（随 ETABS 22+ 安装）；可从 PyPI 安装或用 uvx 运行。可选环境变量如 ETABS_MCP_CONNECT_MODE、ETABS_MCP_READ_ONLY、ETABS_MCP_TOKEN 用于配置连接、安全与 HTTP 认证。长时间分析可能需要调高客户端的工具超时。
安装前请注意
它会写入真实的 ETABS 模型：分析、设计、表格编辑、删除、新建/打开模型、解锁与关闭都会改动或丢弃数据，破坏性调用默认需要 confirm=true，除非设置 ETABS_MCP_ALLOW_DESTRUCTIVE。只读模式与审计日志需手动开启。通过 HTTP 在 localhost 之外提供服务时必须携带 ETABS_MCP_TOKEN 令牌。它会启动或附着到桌面版 ETABS，并可截取屏幕。

安装

在 SourceWeft 中

  1. 打开 控制台中的 ETABS MCP，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

[An AI agent models, analyses, designs and iterates a 6-storey steel building in ETABS through etabs-mcp]

Rendered from a live ETABS 23 session: every member, deflection and D/C ratio is real. MP4

etabs-mcp

Your AI agent, inside ETABS.

An agentic Model Context Protocol server for CSI ETABS v22+. Claude Code, Codex, Factory Droid, Cursor and any other MCP client can model, load, analyse, design and inspect structures the way an engineer does, through the official ETABS API, with every call checked against the real signatures.

[Python] [ETABS] [MCP] [Tests] [License: Apache-2.0]

Quick start · Tools · How it works · Testing · Configuration

Why

ETABS has a huge automation API: 143 interfaces, 1,293 reachable methods, 58 enums. It's also full of ref arrays, status codes and silent quirks. Agents should be designing buildings, not wrestling with COM marshalling.

etabs-mcp gives agents two layers:

71 curated toolsEngineer-shaped workflows: etabs_generate_building, etabs_define_seismic_load, etabs_code_checks, etabs_run_analysis, etabs_get_results, etabs_run_design, etabs_render_view, etabs_find_objects, etabs_edit_table, and more.
The entire APIetabs_search_api → etabs_describe_api → etabs_call_api. Every ETABS method is callable with plain JSON, validated against the live signature of the ETABS version you run.

Highlights

Full coverage, zero guesswork
Search all 1,293 methods, read exact signatures with enum values, and call any of them. ByRef outputs come back as named JSON.

Sees like an engineer
etabs_render_view draws the model offscreen from any angle: deformed shapes, D/C ratios, sections, stories. etabs_screenshot shows the real ETABS window.

The Interactive Database
Read any of ETABS's tables and edit importable ones (update / append / delete rows, then apply), with the import log returned.

Safe by design
Destructive calls need confirm=true, internals are blocked, and --read-only mode refuses every write. Tool annotations tell clients what is safe.

Version-adaptive
Finds every ETABS 22/23/24… install, loads that version's ETABSv1.dll and reflects its API live. Methods missing in older versions fail clearly.

Built for agents
Errors carry a code and a hint. Lengths accept "6 m" or "20 ft", long runs go to background jobs, and etabs_what_changed notices hand edits in ETABS.

Quick start

Requirements: Windows · ETABS 22 or newer (licensed) · Python 3.10+ · the .NET 8 Desktop Runtime (installed with ETABS 22+).

Install from PyPI:

bash
pip install etabs-mcp

Or run it without installing, using uv:

bash
uvx etabs-mcp --list-installs

Claude Desktop, one click: download etabs-mcp-<version>-py3XX.mcpb for your Python version from the latest release and open it. Claude Desktop installs the extension with every dependency bundled.

Check that it finds ETABS:

bash
etabs-mcp --list-installs

Connect your agent

Claude Code
bash
claude mcp add etabs -- etabs-mcp

Analyses can take minutes on big models; raise the tool timeout with MCP_TOOL_TIMEOUT=600000.

OpenAI Codex

~/.codex/config.toml

toml
[mcp_servers.etabs]command = "etabs-mcp"tool_timeout_sec = 600
Factory Droid · Cursor · Claude Desktop · Windsurf · any MCP client
json
{  "mcpServers": {    "etabs": {      "command": "etabs-mcp",      "env": { "ETABS_MCP_CONNECT_MODE": "auto" }    }  }}
HTTP (remote agents, multiple clients)
bash
etabs-mcp --transport streamable-http --port 8765

Then just ask:

"Model a 2-storey steel frame, 2×1 bays of 6 m × 5 m, W14X90 columns, W18X35 beams, 200 mm slab. Apply 1.5 kPa SDL and 3 kPa live, run the analysis, report T₁, wind drift and the worst steel D/C ratio, and show me the 3D view."

The server connects on its own: it attaches to a running ETABS, or launches one.

71 tools

AreaTools
Sessionetabs_list_installations · etabs_connect · etabs_status · etabs_disconnect
Model & fileetabs_model_overview · etabs_new_model · etabs_open_model · etabs_save_model · etabs_set_units · etabs_get_stories · etabs_set_stories
Geometryetabs_add_frames · etabs_add_areas · etabs_add_points · etabs_list_objects · etabs_delete_objects · etabs_set_restraints · etabs_assign_section · etabs_select
Propertiesetabs_list_properties · etabs_define_material · etabs_define_frame_section · etabs_define_area_section
Loadsetabs_define_load_patterns · etabs_assign_loads · etabs_define_combinations · etabs_list_load_definitions
Lateral systemetabs_define_seismic_load (ASCE 7-16 ELF) · etabs_define_wind_load (ASCE 7-16/7-22, other codes via fields) · etabs_define_response_spectrum · etabs_set_mass_source · etabs_assign_diaphragm · etabs_set_modal_case
Generateetabs_generate_building: grids, stories, steel moment/braced or concrete frame/wall systems, slabs, supports, diaphragm and gravity loads in one call
Analysis & designetabs_run_analysis · etabs_analysis_status · etabs_unlock_model · etabs_get_results · etabs_run_design · etabs_get_design_summary · etabs_design_codes
Concrete & wallsetabs_get_concrete_design (beams, columns, joints) · etabs_run_shear_wall_design · etabs_get_wall_design (piers, spandrels) · etabs_get_slab_design (strips, punching)
Code checksetabs_code_checks (drift, torsional/soft-story/weight irregularity, modal mass, RS vs ELF) · etabs_scale_response_spectrum
Background jobsetabs_job_status · etabs_job_wait: analysis and design with background=true never hit client timeouts
Database tablesetabs_list_tables · etabs_get_table · etabs_edit_table
See & queryetabs_render_view · etabs_find_objects · etabs_screenshot · etabs_show_window · etabs_refresh_view
Track & undoetabs_what_changed · etabs_checkpoint · etabs_list_checkpoints · etabs_restore_checkpoint
Export & reportetabs_export_model (full .e2k text, paged) · etabs_design_report (Markdown) · etabs_assign_label (groups, piers, spandrels)
Menus & dialogsetabs_menu (browse and run ETABS menu commands the API lacks) · etabs_dialogs
Instancesetabs_instances: drive several ETABS at once (etabs_connect(instance=...)), switch, remove
Entire APIetabs_search_api · etabs_describe_api · etabs_call_api · etabs_call_api_batch

Plus resources (etabs://api/interfaces, etabs://api/interface/{name}, etabs://api/enum/{name}, etabs://server/info) and a prompt (etabs_build_and_check) that walks an agent through the full workflow.

Example: anything the curated tools don't cover
jsonc
// 1. find itetabs_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 typesetabs_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": { ... } }

What the agent sees

The film above is cut from one recorded session. An agent built a 6-storey, 4×3-bay braced steel building through etabs-mcp, analysed it, ran the AISC 360-16 check, found 48 overstressed girders, upsized them, and re-ran everything until no member was over capacity.

[Model: 354 members and 72 slabs][Design: 48 members over capacity, max D/C 1.22][Iterate: 0 members over capacity, max D/C 0.91]
Model · 354 members, 72 slabs, 30 tool callsDesign · 48 over capacity, max D/C 1.22Iterate · W24X76 × 48 → 0 over capacity, max D/C 0.91

etabs_render_view

The agent's own view of the model, drawn from its data. It works with ETABS hidden, never takes focus, and shows what the ETABS API cannot switch the GUI to.

[Members coloured by design ratio][Deformed shape under ASCE 7-16 seismic load][Light theme, coloured by section]
color_by="design_ratio"deformed_case="EQX", color_by="displacement"color_by="section", theme="light"
[The same model in the real ETABS window, captured by etabs_screenshot]

The same model in ETABS itself, captured by the agent with etabs_screenshot.

How it works

mermaid
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

Reverse-engineering the API, not ETABS. This server stays on the official, documented OAPI and never patches or decompiles the ETABS engine. Its API surface was mapped from the shipped interop assembly:

  1. REA static metadata analysis of ETABSv1.dll: 365 types, 3,275 method defs, 14,752 parameters.
  2. A reflection dumper (tools/ApiDump) emits every public interface, signature, ByRef flag, default and enum into etabs_api_spec.json.
  3. Cross-check: reflection and raw metadata agree exactly (e.g. cFrameObj + cAnalysisResults + cDatabaseTables = 136 methods + 1 property accessor = REA's 137).
  4. At runtime the server re-reflects the loaded DLL, so validation always matches the ETABS you run.

Engineering details that make it "just work":

  • Typed marshalling. pythonnet boxes Python int as PyInt inside object[], which reflection rejects for Int32. Every argument is routed through a one-element typed array and Array.Copy, so ETABS gets real Int32/Double/enum boxes and ByRef arrays.
  • One thread. ETABS and COM proxies aren't thread-safe; every call is serialised on a single worker.
  • Lost connections (ETABS closed or crashed) are detected from HRESULTs and reported with a reconnect hint.
  • ETABS quirks handled:
    • Library imports that ETABS silently renames (W14X90 → W14X90-1) are detected and renamed back.
    • After table edits, ETABS reports the model file as the temporary .$et; saving is mapped back to .EDB.
    • Unitless result columns (drift ratios, mass ratios) are turned into numbers, while IDs like Label: "1" stay strings.
    • GPU-drawn viewports are blank to PrintWindow, so screenshots come from the composed screen and focus is handed back afterwards.

Tested against real ETABS

Offline (CI): 58 tests. Every curated tool runs through FastMCP against a fake backend that resolves and coerces every call against the real ETABSv1.dll catalog. A wrong method or parameter name fails exactly as it would in ETABS.

Live end-to-end: tests/live/test_live_e2e.py starts the server as a real MCP subprocess, launches ETABS 23.3.2, and runs 42 tool calls with 0 failures in ~42 s:

StepVerified
Model2 storeys, 26 frames (library W-shapes), 4 slabs, 6 fixed supports
LoadsSDL / LL / wind patterns, area + line + joint loads, 2 combos + AISC defaults
Analysisall cases finished in 9.8 s; model locks
Base reactionsLL ΣFz = 360 kN = 3 kPa × 120 m², exact; SDL matches slab + line-load hand calc
Modal / driftT₁ = 0.398 s · max wind drift 1/1846
Design26 steel members (AISC 360-16), max D/C 0.35, 0 failing
Generic APIreleases set and read back, a 9-call batch, status-code failures, validation and confirm errors
Tablesread 26 section assignments, edit one through the Interactive Database, verify through the API
Lifecycleunlock, save (.EDB), screenshot, clean ETABS shutdown

Live v0.2 suite: tests/live/test_live_v2.py drives every new tool against ETABS on a 3-storey, 63-member model:

StepVerified
Units"3.5 m", "4200 mm", "500 mm" inputs land as the right values
Find & label27 columns, 12 beams on Story2, 18 beams ≥ 7.5 m (selected), group round-trip
LateralASCE 7-16 seismic (X, X±E), auto wind, ASCE 7-16 spectrum + RS case, mass source, diaphragm on 12 slabs, 9 modes
Change trackinga hand edit and an added beam are both reported; the checkpoint restores the model
Background jobsanalysis returns at once; other calls get busy; job_wait returns the result
ResultsEQX, WX and RSX base shears; X-only seismic gives exactly zero FY
Seeingdesign-ratio, deformed, section and plan renders; AISC 341 design errors flagged, never shown as safe
Export & report.e2k sections, Markdown report with reactions, modes, drifts and design

Live v0.3 suite: tests/live/test_live_v3.py:

StepVerified
Generator4-storey concrete shear-wall building on a non-uniform grid (8/6/8 m); steel braced building in kip-ft
Hand checksteel building LL ΣFz = 0.05 ksf × 90 ft × 50 ft × 3 floors, exact
Code checksdrift (Cd-amplified), torsion, soft story, weight, modal mass (12 modes), RS vs ELF
RS scalingresponse spectrum scaled to 100% of ELF, re-analysed, ratio 1.00 verified
Concrete & wallsACI 318-19 beams, all 48 columns, joints; shear walls designed through the menu, pier results read back

Showcase run (tools/record_demo_data.py): a 6-storey braced steel building, 354 members and 72 slabs. LL ΣFz = 9,720 kN (= 3 kPa × 30 m × 18 m × 6 floors, exact), wind ΣFx = 432 kN (= 18 kN × 24 joints, exact), T₁ = 1.71 s. The redesign loop took max D/C from 1.22 to 0.91.

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

Configuration

Env var / flagDefaultMeaning
ETABS_MCP_CONNECT_MODE / --connect-modeautoattach to a running ETABS, start a new one, or auto (attach if one is open, else start)
ETABS_MCP_VERSION / --etabs-versionnewestETABS major version to use, e.g. 22
ETABS_MCP_INSTALL_DIR / --install-dirautoETABS program folder
ETABS_MCP_VISIBLE / --hiddenvisibleShow the ETABS window when launching
ETABS_MCP_READ_ONLY / --read-onlyoffRefuse every call that changes the model
ETABS_MCP_ALLOW_DESTRUCTIVE / --allow-destructiveoffSkip confirm=true for destructive calls (CI / unattended use)
ETABS_MCP_RUNTIMEcoreclr.NET host for pythonnet (netfx as a fallback)
ETABS_MCP_MAX_ARRAY_ITEMS2000Cap on array lengths returned by etabs_call_api
ETABS_MCP_MAX_TABLE_ROWS500Default page size for tables and results
ETABS_MCP_AUDIT_LOG / --audit-logoffAppend every model-changing call (time, instance, call, arguments, result) to a JSON-lines file
ETABS_MCP_TOKEN / --tokennoneBearer token for --transport streamable-http/sse; required to listen beyond localhost

Publishing (maintainers)

Tagging vX.Y.Z runs release.yml, which tests, builds the wheel, sdist and .mcpb bundles, and publishes the GitHub release. PyPI and the MCP Registry use tokenless trusted publishing: add a trusted publisher on pypi.org (this repo, workflow release.yml, environment pypi), then set the repository variable PUBLISH_PYPI=true. Later tags publish to PyPI and list the server in the MCP Registry.

Version support

ETABSStatus
23.x✅ Verified live (23.3.2)
22.x✅ Supported: same .NET 8 API; the catalog is reflected from your installed DLL
24+✅ Expected to work: new methods appear automatically through live reflection
≤ 21❌ Not supported (.NET Framework era API)

Safety model

LevelExamplesBehaviour
readGet*, Count*, tables, resultsalways allowed
writeSet*, Add*, analysis, designblocked in read-only mode
destructiveDelete*, new/open model, unlock (deletes results), close ETABSneeds confirm=true
blockedInternalExec, plugin hooks, active-object switchingnever callable

Menu commands run through etabs_menu need confirm=true as well, and over HTTP every request must carry the bearer token.

Project layout

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.dlltools/ApiDump                .NET reflection dumper that produced the API spectools/record_demo_data.py    drives the MCP tools against live ETABS and records the showcase datatools/render_hero.py         renders the README film and stills from that datatools/build_mcpb.py          builds the Claude Desktop extensionstests/             offline suite + live end-to-end test

Troubleshooting

  • install_not_found: run etabs-mcp --list-installs; set ETABS_MCP_INSTALL_DIR if ETABS lives somewhere unusual.
  • Attaching does nothing: wait until ETABS has finished starting and close any modal dialogs; or pass pid to etabs_connect.
  • Edits fail after analysis: the model is locked. etabs_unlock_model(confirm=true) deletes results and unlocks it.
  • Long analyses time out in the client: raise the client's MCP tool timeout (see Connect your agent).
  • Switching ETABS major versions: restart the server; one process hosts one ETABSv1.dll.

Apache-2.0 © Moha2005269 · ETABS is a trademark of Computers and Structures, Inc. This project is independent and not affiliated with or endorsed by CSI.

来源：README.md，提交 288df2b

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.3.2最新Oct 18, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分