Drive OpenBrIM with an AI Agent (Desktop App)

The OpenBrIM Desktop app wraps the OpenBrIM web app in a desktop window and runs a small local server that an AI agent — Claude (Desktop / cowork) or Codex — can connect to. The agent drives your model with the same actions you do in the UI (create objects, set parameters, run analysis, read results, export, …) while you watch and review each step in the live 3D window.

The server runs only on your own machine (127.0.0.1) and is protected by a token. The agent is a client that connects to it — nothing is exposed to the internet.

1. Install the app

1. Download the latest installer from the Releases page (OpenBrIM Desktop Setup x.y.z.exe).
2. Run it. The app updates itself automatically when a new version is released, so you only install once.

2. First run — open a project

1. On first launch, enter your workspace URL (<companyname>.openbrim.org) and sign in.
2. Open (or create) a project. Keep this window open while you work with the agent.

3. Get your connection details

In the menu bar choose Agent → Connect your AI agent…. The dialog shows two things:

• URL: http://127.0.0.1:8765/mcp
• Token: a long secret string (treat it like a password)

Click Copy config to copy a ready-made configuration block (URL + token already filled in).

Your URL/token are unique to your install. Use the values shown in your app, not the examples below.

4. Connect Claude (Desktop / cowork)

Add the copied block to your claude_desktop_config.json (Claude Desktop → Settings → Developer → Edit Config), then restart Claude:

{
  "mcpServers": {
    "openbrim-modeler": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "http://127.0.0.1:8765/mcp",
        "--header", "Authorization: Bearer <YOUR-TOKEN>"
      ]
    }
  }
}

After restarting, Claude shows the openbrim-modeler tools. Ask it to do something and it will drive the OpenBrIM Desktop window.

5. Connect Codex

Add the same server to your Codex config.toml under [mcp_servers.openbrim]:

[mcp_servers.openbrim]
command = "npx"
args = ["-y", "mcp-remote", "http://127.0.0.1:8765/mcp", "--header", "Authorization: Bearer <YOUR-TOKEN>"]

Restart Codex; it will pick up the OpenBrIM tools.

Both clients use the same local server, so you can connect either one (or both). The OpenBrIM Desktop app must be running with a project open for the tools to work.

6. Use it

Just ask in plain language. The agent picks the right tools and you see each change in the live window; model-changing actions also return a screenshot in the chat. Examples:

• "Open a new steel I‑girder bridge template and add a superstructure and substructure."
• "List the support lines, then set the second one's station to 150 ft."
• "Validate the model, fix any issues, then analyze it."
• "Show me the deformed shape for the girder stage and report the maximum displacement."
• "Export the model to STAAD and Excel."
• "List the project revisions and revert to the one from this morning."

What the agent can do, grouped. Each row lists the kind of work it can carry out for you.

Projects & templates

• Browse and open projects — list your projects and recently opened ones, and open any of them by name.
• Start from a template — list the available New‑Project templates (steel I‑girder, tub girder, concrete U‑girder, …) and create a new project from one, optionally overriding the template's default parameters.
• Follow the workflow — read the project's workflow steps in order (the intended input sequence) and work through them one item at a time, including each item's documentation link.

Build & edit the model

• Inspect before editing — list objects (optionally filtered by type), read any object's parameters (expression + evaluated value) and children, and look up an object type's input schema (what inputs it needs, their units, and what its references point to) before creating it.
• Create, edit, delete — add objects exactly the way the spreadsheet's "new row" does, set one or many parameters, and delete objects. Every model‑changing action recompiles and returns a screenshot for review.
• Bulk / rebuild — run many create/edit/delete operations under a single recompile to build or rebuild a model quickly.
• Units handled correctly — the agent reads the project's internal units and converts your real‑world values (e.g. 100 ft, 90°) before writing them, so geometry lands where you expect.
• Undo / redo / recompile — step changes back and forth and force a redraw.

Materials & sections (from the shared library)

• Import standard materials — search the shared material databases (concrete grades like Fc_4ksi, steel grades like A709_50, AASHTO grades) and import the one you pick into the project so objects can reference it by name.
• Import standard sections — search the section/shape databases (AISC rolled shapes such as W36, HSS, plus beam/box/girder databases) and import a chosen shape into the project.

Import external geometry

• LandXML — import a LandXML file (horizontal/vertical alignments and surfaces) straight from disk into the model.

Generators

• Run generative objects — list the template's generative objects and run one to emit a whole sub‑assembly in a single step: e.g. multi‑column bent, hammerhead pier, straddle bent, pile cap, the steel/concrete code‑check generators, and the construction & loading (staged‑construction) generators. The agent first reads each generator's exact inputs, then generates.

Validation & errors

• Check the inputs — read the project's validation issues (the same list the Validation Issues panel shows) after setting parameters, so problems get caught and fixed.
• Surface generation errors — read (and clear) the generation/render errors that would otherwise pop the blocking "Uh, Houston…" dialog, then fix the offending object.

Analysis, design & results

• Analyze — run the FEA analysis and wait for it to finish.
• Design — run the design‑code checks and report PASSED/FAILED, then open or read the detailed design report.
• Explore results visually — list the analysis cases (load cases, combinations, eigen modes, and staged‑construction stages), switch the FEA view to a case, and view its deformed shape, loading, forces or stresses.
• Read result values — pull the actual numbers — nodal displacements, support reactions, line/member forces, shell forces, FE composite forces — for any case or construction stage, in display units (the same numbers the FEA spreadsheet/Excel export show).
• Screenshots — capture the full window or just the clean 3D/FEA canvas, switch between Model / FEA / CAD / Documents views, and zoom‑to‑extents to frame the whole model.

Revisions

• History — list the project's server snapshots, compare two revisions (added/deleted objects and changed parameters), and revert to an earlier one.

FE core (raw finite‑element modeling)

• Build elements directly — create FE nodes (with supports: fixed / pinned / roller / explicit DOF springs), line elements (beam, truss, tension/compression‑only, cable), shell surfaces (tri/quad), and springs (support or link).
• Loads & cases — create analysis load cases (with AASHTO load types and optional self‑weight) and add nodal forces/moments.
• Whole‑model build & templates — build an entire FE model in one recompile, list the FE core objects, or drop in a ready‑made analyzable template (simply‑supported beam, portal frame, truss).

Export

• Interchange & analysis files — export the project to STAAD, SAP2000, CSiBridge, Midas, OpenSees, LARSA, OBJ, glTF, DXF (2D/3D), Tekla, IFC, DGN, or Excel. Files are written to your Documents/OpenBrIM Exports folder. (Analyze first if you want an export that reflects results.)

7. Review every step (recommended)

Each model‑changing action triggers your agent's approval prompt before it runs, and returns a screenshot afterward — so you stay in control. Don't blanket‑"always allow" the mutating tools; review them as they come.

Troubleshooting

• No OpenBrIM tools in the agent — make sure the app is running with a project open, you restarted the agent after editing its config, and the token matches the one in Agent → Connect your AI agent….
• "unauthorized" / 401 — the token is wrong or missing from the Authorization: Bearer header.
• Tools call but nothing happens — a project must be loaded in the window; open one first.