ETABS MCP

_{ETABS 23 のライブセッションからレンダリング：すべての部材、たわみ、D/C 比は実際の値です。MP4}

etabs-mcp

ETABS の中で使える AI エージェント。

CSI ETABS v22+ 向けのエージェント型 Model Context Protocol サーバーです。Claude Code、Codex、Factory Droid、Cursor など、あらゆる MCP クライアントが、エンジニアと同じ方法で、公式 ETABS API を通じて構造物のモデル化、荷重設定、解析、設計、検査を行えます。すべての呼び出しは実際のシグネチャと照合されます。

クイックスタート · ツール · 仕組み · テスト · 設定

特長

ETABS には膨大な自動化 API があり、143 のインターフェース、到達可能な 1,293 のメソッド、58 の列挙型を備えています。一方で、ref 配列、ステータスコード、表面化しにくい癖も数多くあります。エージェントが取り組むべきなのは建物の設計であり、COM マーシャリングとの格闘ではありません。

etabs-mcp は、エージェントに次の 2 つのレイヤーを提供します。

主な特長

クイックスタート

要件： Windows · ETABS 22 以降（ライセンス取得済み） · Python 3.10+ · .NET 8 Desktop Runtime（ETABS 22 以降とともにインストールされます）。

PyPI からインストールします：

pip install etabs-mcp

または、uv を使ってインストールせずに実行します：

uvx etabs-mcp --list-installs

Claude Desktop ならワンクリック： お使いの Python バージョンに対応する etabs-mcp-<version>-py3XX.mcpb を 最新リリースからダウンロードして開きます。Claude Desktop は すべての依存関係を含む拡張機能をインストールします。

ETABS が検出されることを確認します：

etabs-mcp --list-installs

エージェントを接続する

claude mcp add etabs -- etabs-mcp

[mcp_servers.etabs]
command = "etabs-mcp"
tool_timeout_sec = 600

{
  "mcpServers": {
    "etabs": {
      "command": "etabs-mcp",
      "env": { "ETABS_MCP_CONNECT_MODE": "auto" }
    }
  }
}

etabs-mcp --transport streamable-http --port 8765

あとは、次のように依頼するだけです：

「2 層の鉄骨フレームをモデル化してください。6 m × 5 m のスパンを 2×1 ベイ配置とし、柱は W14X90、梁は W18X35、スラブ厚は 200 mm にします。 SDL 1.5 kPa と積載荷重 3 kPa を適用して解析を実行し、T₁、風による層間変位、鉄骨の最大 D/C 比を報告し、 3D ビューも表示してください。」

サーバーは自動的に接続します。実行中の ETABS に接続するか、ETABS を起動します。

71 個のツール

さらに、リソース (etabs://api/interfaces、etabs://api/interface/{name}、etabs://api/enum/{name}、 etabs://server/info) と、エージェントをワークフロー全体に沿って案内するプロンプト (etabs_build_and_check) があります。

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

エージェントに見えるもの

上の映像は、1回の記録されたセッションから切り出したものです。エージェントは etabs-mcp を通じて6階建て、4×3スパンのブレース付き鉄骨建物を構築し、解析を実行し、AISC 360-16 のチェックを行いました。応力超過の梁が48本見つかったため、断面を大きくしてすべてを再実行し、どの部材も耐力を超えなくなるまで繰り返しました。

モデル · 部材354本、スラブ72枚、ツール呼び出し30回	設計 · 耐力超過48本、最大D/C 1.22	反復 · W24X76 × 48 → 耐力超過0本、最大D/C 0.91

etabs_render_view

モデルのデータをもとに描画された、エージェント独自のビューです。ETABSを非表示にした状態で動作し、フォーカスを奪うこともありません。また、ETABS APIではGUIを切り替えられないビューも表示できます。

color_by="design_ratio"	deformed_case="EQX", color_by="displacement"	color_by="section", theme="light"

_{エージェントが etabs_screenshot でキャプチャした、ETABS自体に表示された同じモデル。}

動作の仕組み

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

ETABS ではなく、API をリバースエンジニアリングしています。 このサーバーは公式に文書化された OAPI のみを使用し、ETABS エンジンへのパッチ適用や逆コンパイルは行いません。API の範囲は、同梱されている相互運用アセンブリからマッピングしました。

1. ETABSv1.dll の REA 静的メタデータ分析：365 型、3,275 メソッド定義、14,752 パラメーター。
2. リフレクションダンパー（tools/ApiDump）が、すべてのパブリックインターフェイス、シグネチャ、ByRef フラグ、デフォルト値、列挙型を etabs_api_spec.json に出力します。
3. 相互検証： リフレクションと生のメタデータは完全に一致します（例：cFrameObj + cAnalysisResults + cDatabaseTables = 136 メソッド + 1 プロパティアクセサー = REA の 137）。
4. 実行時にサーバーは読み込まれた DLL を再度リフレクションするため、検証結果は常に実行中の ETABS と一致します。

「そのまま動く」ためのエンジニアリング上の工夫：

• 型付きマーシャリング。 pythonnet は Python の int を object[] 内で PyInt としてボックス化しますが、リフレクションは Int32 として認識しません。すべての引数を 1 要素の型付き配列と Array.Copy 経由で渡すことで、ETABS は正しい Int32／Double／列挙型のボックスと ByRef 配列を受け取ります。
• 単一スレッド。 ETABS と COM プロキシはスレッドセーフではないため、すべての呼び出しは単一のワーカー上で直列化されます。
• 接続の切断（ETABS の終了またはクラッシュ）は HRESULT から検出され、再接続のヒントとともに報告されます。
• ETABS の癖への対応：
  • ETABS が暗黙に名前を変更するライブラリのインポート（W14X90 → W14X90-1）を検出し、元の名前に戻します。
  • テーブルを編集した後、ETABS はモデルファイルを一時的な .$et として報告します。保存時には .EDB に戻します。
  • 単位のない結果列（ドリフト比、質量比）は数値に変換する一方、Label: "1" のような ID は文字列のまま保持します。
  • GPU で描画されるビューポートは PrintWindow では空白になるため、スクリーンショットは合成済みの画面から取得し、その後フォーカスを戻します。

実際の ETABS でテスト済み

オフライン（CI）： 58 件のテスト。厳選された各ツールを FastMCP 経由で実行し、すべての呼び出しを解決して、実際の ETABSv1.dll カタログに照らして型変換するフェイクバックエンドを使用します。不正なメソッド名やパラメーター名は、ETABS と同じように失敗します。

ライブのエンドツーエンドテスト： tests/live/test_live_e2e.py はサーバーを実際の MCP サブプロセスとして起動し、ETABS 23.3.2 を立ち上げ、約 42 秒で失敗 0 件のツール呼び出し 42 件を実行します。

ライブ v0.2 テストスイート： tests/live/test_live_v2.py は、3 階建て、部材 63 本のモデルで、追加されたすべてのツールを ETABS に対して実行します。

ライブ v0.3 テストスイート： tests/live/test_live_v3.py：

ショーケース実行（tools/record_demo_data.py）：6 階建ての鉄骨ブレース建物、部材 354 本、スラブ 72 枚。LL ΣFz = 9,720 kN（= 3 kPa × 30 m × 18 m × 6 階、完全一致）、風荷重 ΣFx = 432 kN（= 18 kN × 24 節点、完全一致）、T₁ = 1.71 s。再設計ループにより、最大 D/C は 1.22 から 0.91 になりました。

pip install -e ".[dev]"
pytest                                   # offline suite
ETABS_MCP_ARTIFACTS=docs/live pytest tests/live --live -s   # drives your local ETABS

設定

公開（メンテナー向け）

vX.Y.Z のタグを付けると release.yml が実行され、テスト、wheel と sdist、.mcpb バンドルのビルド、GitHub リリースの公開が行われます。PyPI と MCP Registry では、トークン不要の信頼済み公開を使用します。pypi.org に信頼済み発行者（このリポジトリ、ワークフロー release.yml、環境 pypi）を追加し、リポジトリ変数 PUBLISH_PYPI=true を設定してください。以降のタグでは PyPI に公開され、MCP Registry にサーバーが登録されます。

バージョンサポート

安全性モデル

etabs_menu 経由で実行するメニューコマンドにも confirm=true が必要です。また、HTTP 経由ではすべてのリクエストにベアラートークンを含める必要があります。

プロジェクト構成

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

トラブルシューティング

• install_not_found：etabs-mcp --list-installs を実行してください。ETABS が通常とは異なる場所にある場合は、ETABS_MCP_INSTALL_DIR を設定してください。
• 接続しても何も起こらない：ETABS の起動が完了するまで待ち、モーダルダイアログをすべて閉じてください。または etabs_connect に pid を渡してください。
• 解析後に編集できない：モデルがロックされています。etabs_unlock_model(confirm=true) は結果を削除してロックを解除します。
• 長時間の解析がクライアントでタイムアウトする：クライアントの MCP ツールのタイムアウトを延長してください（エージェントを接続するを参照）。
• ETABS のメジャーバージョンを切り替える：サーバーを再起動してください。1 つのプロセスでホストできる ETABSv1.dll は 1 つです。