Content
# 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:
```bash
git clone https://github.com/mdvaleed7/ETABS-mcp.git
cd ETABS-mcp
pip install -e .
```
Or with `uv`:
```bash
uv pip install -e .
```
2. Verify the entry point is registered:
```bash
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):
```json
{
"mcpServers": {
"etabs": {
"command": "etabs-mcp",
"args": []
}
}
}
```
If `etabs-mcp` is not on your PATH, use the full path to the script, e.g.:
```json
{
"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
```bash
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:
```jsonc
// 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](https://github.com/jlowin/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
Connection Info
You Might Also Like
No recommendations available