_{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

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

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.

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