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.

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:

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:

pip install etabs-mcp

Or run it without installing, using uv:

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:

etabs-mcp --list-installs

Connect your agent

Claude Code

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

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

Factory Droid · Cursor · Claude Desktop · Windsurf · any MCP client

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

HTTP (remote agents, multiple clients)

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

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

// 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": { ... } }

---

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, 72 slabs, 30 tool calls Design · 48 over capacity, max D/C 1.22 Iterate · 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.

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

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

---

How it works

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:

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

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

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.

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

---

Configuration

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

Safety model

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.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

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.