Agentic MCP server for CSI ETABS v22+: model, load, analyse, design and inspect structures.
io.github.Moha2005269/etabs-mcp — Model Context Protocol (MCP) Server
This MCP server is an agentic interface for CSI ETABS v22+ workflows. It supports modeling, loading, analysis, design, and inspection of structures, with the server description indicating it is focused on ETABS capabilities for engineering tasks.
🛠️ Key Features
Agentic MCP server
CSI ETABS v22+ support
Model, load, analyse, design, and inspect structures
🚀 Use Cases
Structuring modeling in ETABS v22+
Running load and analysis workflows
Performing design and inspection steps in ETABS
⚡ Developer Benefits
Provides an MCP server interface tied to CSI ETABS v22+
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.
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 tools
Engineer-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 API
etabs_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+).
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.
"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.
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.
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:
REA static metadata analysis of ETABSv1.dll: 365 types, 3,275 method defs, 14,752 parameters.
A reflection dumper (tools/ApiDump) emits every public interface, signature, ByRef flag, default and enum
into etabs_api_spec.json.
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:
4-storey concrete shear-wall building on a non-uniform grid (8/6/8 m); steel braced building in kip-ft
Hand check
steel building LL ΣFz = 0.05 ksf × 90 ft × 50 ft × 3 floors, exact
Code checks
drift (Cd-amplified), torsion, soft story, weight, modal mass (12 modes), RS vs ELF
RS scaling
response spectrum scaled to 100% of ELF, re-analysed, ratio 1.00 verified
Concrete & walls
ACI 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 suite
ETABS_MCP_ARTIFACTS=docs/live pytest tests/live --live -s # drives your local ETABS
Configuration
Env var / flag
Default
Meaning
ETABS_MCP_CONNECT_MODE / --connect-mode
auto
attach to a running ETABS, start a new one, or auto (attach if one is open, else start)
ETABS_MCP_VERSION / --etabs-version
newest
ETABS major version to use, e.g. 22
ETABS_MCP_INSTALL_DIR / --install-dir
auto
ETABS program folder
ETABS_MCP_VISIBLE / --hidden
visible
Show the ETABS window when launching
ETABS_MCP_READ_ONLY / --read-only
off
Refuse every call that changes the model
ETABS_MCP_ALLOW_DESTRUCTIVE / --allow-destructive
off
Skip confirm=true for destructive calls (CI / unattended use)
ETABS_MCP_RUNTIME
coreclr
.NET host for pythonnet (netfx as a fallback)
ETABS_MCP_MAX_ARRAY_ITEMS
2000
Cap on array lengths returned by etabs_call_api
ETABS_MCP_MAX_TABLE_ROWS
500
Default page size for tables and results
ETABS_MCP_AUDIT_LOG / --audit-log
off
Append every model-changing call (time, instance, call, arguments, result) to a JSON-lines file
ETABS_MCP_TOKEN / --token
none
Bearer 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
ETABS
Status
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
Level
Examples
Behaviour
read
Get*, Count*, tables, results
always allowed
write
Set*, Add*, analysis, design
blocked in read-only mode
destructive
Delete*, new/open model, unlock (deletes results), close ETABS
Menu commands run through etabs_menu need confirm=true as well, and over HTTP every request must carry the
bearer token.
Project layout
code
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.