ETABS MCP

io.github.Moha2005269Published by GitHub account Moha2005269v0.3.2Updated Nov 1, 2026

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

VerifiedSTDIODesktop onlyDeveloper ToolsData & Analytics

Overview

AI-generated overview

Drives CSI ETABS v22+ from an AI assistant: build, load, analyse, design and inspect structural models through the official ETABS API.

What you can do
  • Manage the ETABS session: list installations, connect, check status, disconnect, and drive several instances.
  • Build and edit models: stories, grids, frames, areas, points, sections, materials, restraints, and generate whole buildings in one call.
  • Define loads and lateral systems: load patterns, combinations, ASCE 7 seismic and wind, response spectra, mass source, diaphragms.
  • Run analysis and design, then read results, D/C ratios, concrete and wall design, and code checks such as drift and irregularities.
  • Read and edit Interactive Database tables, render or screenshot views, export .e2k models and Markdown design reports.
  • Search, describe and call any of the roughly 1,300 ETABS API methods…
When to use it
Useful when an assistant should work inside a licensed ETABS installation on Windows: generating and iterating on building models, running analyses and code checks, or automating repetitive ETABS workflows that would otherwise be done by hand in the GUI.
Requirements
Windows desktop with a licensed ETABS 22 or newer installed, Python 3.10+ and the .NET 8 Desktop Runtime (shipped with ETABS 22+); installed from PyPI or run with uvx. Optional environment variables such as ETABS_MCP_CONNECT_MODE, ETABS_MCP_READ_ONLY and ETABS_MCP_TOKEN configure connection, safety and HTTP auth. Long analyses may need a raised client tool timeout.
Before you install
It writes to real ETABS models: analysis, design, table edits, deletes, new/open model, unlock and close change or discard data, and destructive calls need confirm=true unless ETABS_MCP_ALLOW_DESTRUCTIVE is set. Read-only mode and audit logging are opt-in. Serving over HTTP beyond localhost requires the ETABS_MCP_TOKEN bearer token. It launches or attaches to a desktop ETABS instance and can capture the screen.

Installation

In SourceWeft

  1. Open ETABS MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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.

Source: README.md at commit 288df2b

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.3.2LatestOct 18, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts