etabs-mcp

<!-- mcp-name: io.github.Moha2005269/etabs-mcp -->
<div align="center">

<img src="https://raw.githubusercontent.com/Moha2005269/etabs-mcp/main/docs/assets/hero.webp" alt="An AI agent models, analyses, designs and iterates a 6-storey steel building in ETABS through etabs-mcp" width="100%">

<sub>Rendered from a live ETABS 23 session: every member, deflection and D/C ratio is real. <a href="https://github.com/Moha2005269/etabs-mcp/raw/main/docs/assets/hero.mp4">MP4</a></sub>

# 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](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![ETABS](https://img.shields.io/badge/ETABS-v22%2B-0078D7)](#version-support)
[![MCP](https://img.shields.io/badge/MCP-stdio%20%7C%20HTTP-7C5CFF)](https://modelcontextprotocol.io)
[![Tests](https://img.shields.io/badge/tests-39%20offline%20%2B%20live%20E2E-22C55E)](#tested-against-real-etabs)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-black)](LICENSE)

[Quick start](#quick-start) · [Tools](#71-tools) · [How it works](#how-it-works) · [Testing](#tested-against-real-etabs) · [Configuration](#configuration)

</div>

---

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

<table>
<tr>
<td width="33%" valign="top">

**Full coverage, zero guesswork**<br>
Search all 1,293 methods, read exact signatures with enum values, and call any of them. ByRef outputs come back as named JSON.

</td>
<td width="33%" valign="top">

**Sees like an engineer**<br>
`etabs_render_view` draws the model offscreen from any angle: deformed shapes, D/C ratios, sections, stories. `etabs_screenshot` shows the real ETABS window.

</td>
<td width="33%" valign="top">

**The Interactive Database**<br>
Read any of ETABS's tables and **edit importable ones** (update / append / delete rows, then apply), with the import log returned.

</td>
</tr>
<tr>
<td valign="top">

**Safe by design**<br>
Destructive calls need `confirm=true`, internals are blocked, and `--read-only` mode refuses every write. Tool annotations tell clients what is safe.

</td>
<td valign="top">

**Version-adaptive**<br>
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.

</td>
<td valign="top">

**Built for agents**<br>
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.

</td>
</tr>
</table>

---

## 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](https://docs.astral.sh/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](https://github.com/Moha2005269/etabs-mcp/releases/latest) 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

<details open>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add etabs -- etabs-mcp
```
Analyses can take minutes on big models; raise the tool timeout with `MCP_TOOL_TIMEOUT=600000`.
</details>

<details>
<summary><b>OpenAI Codex</b></summary>

`~/.codex/config.toml`
```toml
[mcp_servers.etabs]
command = "etabs-mcp"
tool_timeout_sec = 600
```
</details>

<details>
<summary><b>Factory Droid · Cursor · Claude Desktop · Windsurf · any MCP client</b></summary>

```json
{
  "mcpServers": {
    "etabs": {
      "command": "etabs-mcp",
      "env": { "ETABS_MCP_CONNECT_MODE": "auto" }
    }
  }
}
```
</details>

<details>
<summary><b>HTTP (remote agents, multiple clients)</b></summary>

```bash
etabs-mcp --transport streamable-http --port 8765
```
</details>

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

| Area | Tools |
|---|---|
| **Session** | `etabs_list_installations` · `etabs_connect` · `etabs_status` · `etabs_disconnect` |
| **Model & file** | `etabs_model_overview` · `etabs_new_model` · `etabs_open_model` · `etabs_save_model` · `etabs_set_units` · `etabs_get_stories` · `etabs_set_stories` |
| **Geometry** | `etabs_add_frames` · `etabs_add_areas` · `etabs_add_points` · `etabs_list_objects` · `etabs_delete_objects` · `etabs_set_restraints` · `etabs_assign_section` · `etabs_select` |
| **Properties** | `etabs_list_properties` · `etabs_define_material` · `etabs_define_frame_section` · `etabs_define_area_section` |
| **Loads** | `etabs_define_load_patterns` · `etabs_assign_loads` · `etabs_define_combinations` · `etabs_list_load_definitions` |
| **Lateral system** | `etabs_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` |
| **Generate** | `etabs_generate_building`: grids, stories, steel moment/braced or concrete frame/wall systems, slabs, supports, diaphragm and gravity loads in one call |
| **Analysis & design** | `etabs_run_analysis` · `etabs_analysis_status` · `etabs_unlock_model` · `etabs_get_results` · `etabs_run_design` · `etabs_get_design_summary` · `etabs_design_codes` |
| **Concrete & walls** | `etabs_get_concrete_design` (beams, columns, joints) · `etabs_run_shear_wall_design` · `etabs_get_wall_design` (piers, spandrels) · `etabs_get_slab_design` (strips, punching) |
| **Code checks** | `etabs_code_checks` (drift, torsional/soft-story/weight irregularity, modal mass, RS vs ELF) · `etabs_scale_response_spectrum` |
| **Background jobs** | `etabs_job_status` · `etabs_job_wait`: analysis and design with `background=true` never hit client timeouts |
| **Database tables** | `etabs_list_tables` · `etabs_get_table` · `etabs_edit_table` |
| **See & query** | `etabs_render_view` · `etabs_find_objects` · `etabs_screenshot` · `etabs_show_window` · `etabs_refresh_view` |
| **Track & undo** | `etabs_what_changed` · `etabs_checkpoint` · `etabs_list_checkpoints` · `etabs_restore_checkpoint` |
| **Export & report** | `etabs_export_model` (full `.e2k` text, paged) · `etabs_design_report` (Markdown) · `etabs_assign_label` (groups, piers, spandrels) |
| **Menus & dialogs** | `etabs_menu` (browse and run ETABS menu commands the API lacks) · `etabs_dialogs` |
| **Instances** | `etabs_instances`: drive several ETABS at once (`etabs_connect(instance=...)`), switch, remove |
| **Entire API** | `etabs_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.

<details>
<summary><b>Example: anything the curated tools don't cover</b></summary>

```jsonc
// 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": { ... } }
```
</details>

---

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

<table>
<tr>
<td width="33%"><img src="https://raw.githubusercontent.com/Moha2005269/etabs-mcp/main/docs/assets/still_model.png" alt="Model: 354 members and 72 slabs"></td>
<td width="33%"><img src="https://raw.githubusercontent.com/Moha2005269/etabs-mcp/main/docs/assets/still_design.png" alt="Design: 48 members over capacity, max D/C 1.22"></td>
<td width="33%"><img src="https://raw.githubusercontent.com/Moha2005269/etabs-mcp/main/docs/assets/still_iterate.png" alt="Iterate: 0 members over capacity, max D/C 0.91"></td>
</tr>
<tr>
<td align="center"><sub><b>Model</b> · 354 members, 72 slabs, 30 tool calls</sub></td>
<td align="center"><sub><b>Design</b> · 48 over capacity, max D/C 1.22</sub></td>
<td align="center"><sub><b>Iterate</b> · W24X76 × 48 → 0 over capacity, max D/C