ETABS MCP Server

A Model Context Protocol (MCP) server that connects Large Language Models (LLMs) to CSI ETABS, a premier structural engineering software.

This server enables AI assistants (like Claude, Cursor, etc.) to:

• Create, open, and save ETABS models
• Define materials, sections, and structural geometry
• Apply loads and assign properties
• Run structural analysis and design checks
• Extract analysis results and design summaries
• Query and modify ETABS database tables

It uses the comtypes library in Python to interact directly with the ETABSv1 COM API, providing a seamless bridge between modern AI and legacy Windows COM applications.

Prerequisites

• Windows OS (required for COM integration — comtypes does not work on macOS/Linux)
• CSI ETABS installed and licensed (v19, v20, v21, or v22)
• Python 3.10+
• uv (recommended) or pip

Repository Layout

ETABS-mcp/
├── pyproject.toml                # build config & entry point
├── README.md
├── etabs_mcp_config.json         # runtime config (units, auto-connect, …)
├── src/
│   └── etabs_mcp/
│       ├── __init__.py
│       ├── server.py             # FastMCP entry point  (run via `etabs-mcp`)
│       ├── etabs_connection.py   # COM singleton manager
│       ├── helpers.py            # shared utils, units, response formatting
│       └── tools/
│           ├── __init__.py
│           ├── analysis.py
│           ├── assignments.py
│           ├── database_tables.py
│           ├── design.py
│           ├── generic_api.py
│           ├── loads.py
│           ├── model_control.py
│           ├── model_geometry.py
│           ├── properties.py
│           ├── results.py
│           ├── seismic.py                 # IS 1893 modal + RSA + drift
│           ├── selection.py
│           ├── stiffness_modifiers.py     # ACI 318 + IS 456 cracked-section presets
│           └── stories_grids.py

Installation

1. Clone the repo and install the package in editable mode:

   git clone https://github.com/mdvaleed7/ETABS-mcp.git
   cd ETABS-mcp
   pip install -e .

Or with uv:

   uv pip install -e .

1. Verify the entry point is registered:

   etabs-mcp --help

(The server itself only starts speaking MCP over stdio, so don't expect pretty output — just confirm the command exists.)

Configuration for MCP Clients

Claude Desktop

Add this to your claude_desktop_config.json (usually at %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "etabs": {
      "command": "etabs-mcp",
      "args": []
    }
  }
}

If etabs-mcp is not on your PATH, use the full path to the script, e.g.:

{
  "mcpServers": {
    "etabs": {
      "command": "python",
      "args": ["-m", "etabs_mcp.server"]
    }
  }
}

Make sure you run this Python from the same virtual environment where you installed the package.

Cursor

In Cursor settings → Features → MCP, add a new server:

• Type: command
• Name: ETABS
• Command: etabs-mcp (or the full path to your venv's script)

Claude Code / other stdio MCP clients

claude mcp add etabs -- etabs-mcp

Tool Categories

The server exposes 69 tools grouped by domain:

| Category | Tools | Key functions | |---|---|---| | Model Control | 6 | etabs_get_status, etabs_new_model, etabs_open_model, etabs_save_model, etabs_close_model, etabs_set_units | | Geometry | 7 | etabs_add_point, etabs_add_frame, etabs_add_area, etabs_get_all_*, etabs_delete_object | | Stories & Grids | 4 | story/grid definition and retrieval | | Properties | 7 | materials, frame sections (I, tube, concrete), area sections, rebar | | Assignments | 6 | frame section, releases, area section, diaphragm, pier/spandrel labels | | Stiffness Modifiers | 3 | ACI 318-19 + IS 456:2000 cracked-section presets for beams/columns/walls/slabs | | Loads | 7 | patterns, cases (Linear/Modal/RSA/Nonlinear), combinations, point/frame/area loads | | Analysis | 4 | run solver, case status, active DOF, delete results | | Results | 5 | displacements, frame forces, reactions, base reactions | | 🆕 Seismic | 7 | IS 1893:2016 modal + RSA + drift check (see below) | | Design | 4 | steel & concrete design, code setting, summary results | | Database Tables | 4 | full interactive access to ETABS tables | | Selection | 4 | select objects, groups, named selections | | Generic API | 1 | etabs_call_api — escape hatch for all 1,300+ ETABS methods |

---

🆕 Seismic Module — IS 1893:2016 / ASCE 7 / EC8

The new seismic.py module adds 7 tools for complete response spectrum workflow:

| Tool | Purpose | |---|---| | etabs_define_modal_case | Eigenvector/Ritz case; max modes, shift value | | etabs_define_response_spectrum | RSA case — CQC/SRSS, eccentricity, scale factors | | etabs_get_modal_results | Periods, frequencies, mass participation; auto-checks IS 1893 Cl. 7.7.5a 90% mass rule | | etabs_get_story_drifts | Inter-storey drift ratios with IS 1893 Cl. 7.11.1 h/250 check | | etabs_get_story_forces | Storey shear and overturning moments per floor | | etabs_set_is1893_seismic_params | Computes ETABS scale factor from Zone/I/R/soil; step-by-step workflow guide | | etabs_check_is1893_drift | Full X+Y direction drift compliance report with PASS/FAIL per storey |

IS 1893:2016 RSA workflow (6 steps): ```

1. etabs_set_is1893_seismic_params(zone="III", I=1.2, R=5.0) → get scale factor
2. Define IS 1893 spectrum function in ETABS (manually or via etabs_call_api)
3. etabs_define_modal_case("MODAL", max_modes=36)
4. etabs_run_analysis()
5. etabs_get_modal_results("MODAL") → verify ≥ 90% mass (Cl. 7.7.5a)
6. etabs_define_response_spectrum("EQX", scale_x=SF) + "EQY"
7. etabs_check_is1893_drift("EQX", "EQY") → PASS/FAIL report

### Stiffness Modifiers (ACI 318 presets)

The server ships with baked-in ACI 318-19 Table 6.6.3.1.1(a) cracked-section
factors, so an LLM can apply them to a whole model in one tool call.

**One-shot for all four categories** — call `etabs_apply_aci_stiffness_modifiers`
with either explicit names or named ETABS groups per category:

// Apply ACI defaults to all members via groups { "beam_group": "BEAMS", "column_group": "COLUMNS", "wall_group": "WALLS", "slab_group": "SLABS" } ```

Defaults applied:

| Category | Preset | Modifiers | |---|---|---| | Beams | aci_beam | I = 0.35 Ig, torsion = 0.20 | | Columns | aci_column | I = 0.70 Ig, A = 0.70 Ag | | Walls | aci_wall | I = 0.70 Ig, A = 0.70 Ag (uncracked) | | Slabs | aci_slab | I = 0.25 Ig |

Granular tools for finer control:

• etabs_assign_frame_stiffness_modifiers — apply to specific frames with any

of the presets aci_beam, aci_beam_conservative, aci_column, aci_column_conservative, aci_spandrel, aisc_beam, is456_beam, is456_column, is456_beam_seismic, is456_shear_wall — or pass individual area / m2 / m3 / torsion / mass / weight values to override.

• etabs_assign_area_stiffness_modifiers — apply to specific areas with any of

the presets aci_wall, aci_wall_cracked, aci_slab, aci_slab_joist, aci_drop_panel, steel_deck, is456_wall, is456_wall_cracked, is456_slab, is456_flat_slab, is456_ribbed_slab — or override individual f11 / f22 / f12 / m11 / m22 / m12 / v13 / v23 values.

Note on modifier ordering. Frame modifiers are passed to ETABS as [Area, M2, M3, Torsion, M2_weight, M3_weight, Mass, Weight] and area modifiers as [F11, F22, F12, M11, M22, M12, V13, V23]. The Python tool exposes them as named parameters so you never transpose them by accident. If your ETABS version uses a different ordering, use etabs_call_api with interface_path="FrameObj" and method_name="SetModifiers" to pass the raw array directly.

Architecture

This uses the FastMCP framework. Communication with the LLM happens over stdio while communication with ETABS happens via Windows COM (using comtypes).

The server attempts to automatically attach to a running instance of ETABS when started. If it cannot, the LLM can trigger etabs_new_model to launch a fresh instance in the background.

Troubleshooting

| Symptom | Fix | |---|---| | ModuleNotFoundError: No module named 'etabs_mcp' | Run pip install -e . from the repo root (where pyproject.toml lives). | | comtypes import error on macOS/Linux | This is expected — the server only runs on Windows. | | ETABS won't auto-attach | Start ETABS manually, then call etabs_get_status. | | ConnectionError: Cannot launch ETABS | Set etabs_executable_path in etabs_mcp_config.json to the full path of ETABS.exe. |

License

MIT