RISA-3D MCP Server + CLI Toolkit

Connect Claude/ChatGPT to your RISA-3D structural models using the Model Context Protocol (MCP).

Built by a structural engineer to bring AI-assisted workflows to RISA-3D. This MCP server lets you talk to your .r3d files in plain English, no coding required after setup.

Demo

"Summarize this model for a report" "What steel grade is this model using?" "What are the boundary conditions at the column bases?" "Compare these two models and tell me what changed"

Once connected, just point Claude at any .r3d file and start asking questions.

Related MCP server: OpenSTAAD MCP Server

Why This Project Exists

RISA-3D has no public API.

This project bridges that gap by treating .r3d files as the interface, allowing AI assistants to inspect, compare, modify, and report on structural models without automating the RISA application itself.

The goal is to augment structural engineers, not replace engineering judgment.

What Is This?

MCP (Model Context Protocol) is an open standard that lets AI assistants like Claude connect to external tools and files. This server acts as a bridge between Claude Desktop and your RISA-3D models. Claude reads your .r3d files directly and answers questions about them in plain English.

No RISA-3D API is required. This works by reading RISA-3D's plain-text .r3d file format directly. Includes a modular regression test suite to ensure parser and write-tool reliability as the project evolves

Quick Start

git clone https://github.com/vibhanshu-mishra/risa3d-mcp-server.git

cd risa3d-mcp-server

npm install

node risa-cli.js help

For Claude Desktop integration, continue to the Installation section below.

Table of Contents

• Why This Project Exists

• What Is This?

• Quick Start

• Architecture

• Project Structure

• MCP Tools

• Example Prompts

• CLI Usage

• Technical Notes

• Regression Tests

• Roadmap

• Known Limitations

• License

Architecture

             Claude Desktop
                   │
             MCP (index.js)
                   │
              risa-core.js
              /       \
        risa-cli.js  .r3d files

Project Structure

risa3d-mcp-server/
│
├── index.js
├── risa-core.js
├── risa-cli.js
│
├── tests/
│   
│   ├── parser.test.js
│   ├── loads.test.js
│   ├── qc.test.js
│   ├── write-tools.test.js
│   ├── geometry.test.js
│   ├── run-tests.js
│   ├── run-all.js
│   └── test-utils.js
│
├── package.json
├── README.md
└── CHANGELOG.md

What This Server Does

This MCP server reads and modifies .r3d RISA-3D model files. It can:

• Read nodes, members, sections, supports, load cases, and load combinations

• Generate model summaries

• Generate load summaries grouped by RISA basic load case

• Export member schedules to Excel

• Clone a model with controlled changes

• Run QA/QC checks on RISA models

• Run CLI diagnostics without Claude/MCP

Currently includes 40+ MCP tools covering:

• Model interrogation

• QA/QC

• Load Parsing & Validation

• Material Takeoffs

• SAF and Excel Exports

• Model Comparison

• Model Cloning and Editing

• CLI Debugging Toolkit

• Geometry Editing

• Batch Workflows

• Regression-tested Parsing Utilities

Use Without Claude

The project includes a standalone command-line interface (risa-cli.js).

This allows engineers to test parsing logic and generate reports without installing Claude Desktop or using MCP.

Example:

node risa-cli.js generate-load-summary "C:\Models\TEST.r3d"

Useful for:

• Testing parser changes

• Verifying load extraction

• Debugging RISA files

• Running reports locally

What You Can Do

Once connected, you can ask Claude things like:

• "Summarize this model for a report -- include members, nodes, loads, boundary conditions, and materials"

• "What steel grade and Fy value is assigned in this model?"

• "List all the boundary conditions, which nodes are fixed vs. pinned?"

• "What section sizes are assigned to each section set?"

• "List all the members and their section sizes"

• "Run a QC check on this model"

• "Compare these two models and tell me what changed"

• "Export a member schedule for all HSS members"

Requirements

• Windows PC with RISA-3D installed

• Claude Desktop (free)

• Node.js (LTS version -- free)

• A Claude account

Installation

Step 1 -- Install Node.js

Download and install the LTS version from nodejs.org. Click through all the defaults.

Verify it worked, open Command Prompt and run:

node --version
npm --version

Both should return version numbers.

Step 2 -- Download the Project

git clone https://github.com/vibhanshu-mishra/risa3d-mcp-server.git

cd risa3d-mcp-server

npm install

Step 3 -- Test the Server

In Command Prompt, run:

cd risa3d-mcp-server
node index.js

If you see a blinking cursor with no errors, it is working. Press Ctrl+C to stop it.

Step 4 -- Connect to Claude Desktop

1. Install Claude Desktop if you haven't already

2. Press Windows + R, type %APPDATA%\Claude and press Enter

3. Open or create claude_desktop_config.json

4. Paste in the following:

{
  "mcpServers": {
    "risa3d": {
      "command": "node",
      "args": [
        "C:\\path\\to\\risa3d-mcp-server\\index.js"
      ]
    }
  }
}

5. Save the file

6. Fully quit Claude Desktop (right-click the system tray icon -> Quit)

7. Reopen Claude Desktop

Step 5 -- Verify It's Running

In Claude Desktop:

1. Click the + button in the chat input box

2. Click Connectors

3. You should see risa3d listed as connected

Or go to Settings -> Developer and confirm risa3d shows as running.

Example Prompts

Model Reading

Summarize this model for a report:
"C:\path\to\model.r3d"

List all the members in this model.

List all Wide Flange members only.

What materials are defined in this model?

What section sets are defined?

List the boundary conditions.

What load combinations are defined?

QA / QC

Run a QC check on this model.

Check this model for duplicate nodes.

Find all members using HSS8X8X10.

Flag members longer than 20 feet.

Compare these two models and summarize the differences.

Show every member connected to M41.

Show every member connected to node N25.

Editing

Change the Stringer section set from C15X33.9 to C12X20.7 and save as a new model.

Clone this model and change member M41 to HSS6X6X10.

Move node N44 to new coordinates.

Delete members M20 through M25.

Copy member M41 between N200 and N205.

Split member M41 at 50% of its length.

Merge members M41 and M42.

Add a -1.5 k node load to N17 in the DL case.

Add a -0.25 k/ft distributed load to M41 in LL, copying the direction from M40's LL load.

Geometry

Mirror these members about the Y-axis.

Copy these members 20 feet in the X direction.

Add a brace between N44 and a new point at (6,0,-12).

Batch Processing

Summarize every model in this folder.

Replace C15X33.9 with C12X20.7 across all models in this folder.

Run QC on every model in this folder and export an Excel summary.

Export

Export the member schedule to Excel.

Export the load summary to Excel.

Export this model to SAF format.

Generate a material takeoff.

Export every HSS member to a schedule.

MCP Tools

Model Reading & Reporting

QA / QC

Editing Tools

Batch Tools

Export Tools

RISA-3D Load Parsing

RISA-3D .r3d files do not always store visible load case names directly inside load rows. For example, load rows may contain internal raw IDs like:

88
89
90

These are internal RISA load identifiers and should not be assumed to match the visible Basic Load Case numbering shown in the RISA interface.

This project resolves loads using the confirmed RISA pattern:

[BASIC_LOAD_CASES]
  -> distributed load count
  -> area load count
  -> node load count
  -> row order inside load tables

The shared helper parseLoadsByBasicLoadCase(content) groups loads by visible RISA Basic Load Case name, such as:

DL
LL
WLx
WLz
BLC 1 Transient Area Loads

instead of exposing internal raw IDs.

Current Load Editing Support

clone_model_with_changes currently supports:

• Section size changes

• Boundary condition changes

• Member distributed load magnitude changes

• Node load magnitude changes

It does not currently edit area loads.

Adding loads

add_node_load and add_distributed_load add a new row to an existing basic load case:

• The new row is inserted at the end of that case's block of rows, and the case's count in [BASIC_LOAD_CASES] and the section's <n> header are increased, so loads in later cases keep their owner.

• The row is copied from an existing load of the same type in the same case (the first one, or the one on templateNodeLabel / templateMemberLabel). Only the node/member, magnitudes and, for distributed loads, the optional start/end locations are changed. The direction code and RISA's internal load-case ID are copied, because their encoding is not fully decoded.

• A case with no loads of that type cannot be used yet: add one load of that type in RISA-3D first.

• Every saved file is re-checked: load-case counts must match the rows, and every load must point to an existing node or member.

Area loads are intentionally excluded because RISA may generate transient/memberized distributed loads from area loads. Editing the area loads without regenerating those derived loads could create an inconsistent model.

CLI Usage

The CLI lives in risa-cli.js. Run commands from the project folder:

node risa-cli.js help

Generate Load Summary

node risa-cli.js generate-load-summary "C:\path\to\model.r3d"

Include generated transient load cases:

node risa-cli.js generate-load-summary "C:\path\to\model.r3d" --include-transient

Debug Load Case Counts

node risa-cli.js debug-load-case-counts "C:\path\to\model.r3d"

Debug Raw Load Structure

node risa-cli.js debug-load-structure "C:\path\to\model.r3d" 10

Debug Member Load Rows

node risa-cli.js debug-member-load-rows "C:\path\to\model.r3d" M41

Debug Load Membership

node risa-cli.js debug-load-membership "C:\path\to\model.r3d"

MCP Usage

Start the MCP server with:

node index.js

In your MCP client config, point to:

node C:\path\to\risa3d-mcp-server\index.js

Safety Notes

• The server never overwrites the original file when cloning.

• Use clone_model_with_changes with a different outputPath.

• Always open cloned .r3d files in RISA-3D and verify the model before using them for design.

• Write/edit tools should be treated as engineering-assist tools, not final design authority.

Development Workflow

Typical workflow used during development:

1. Add or modify a parser in risa-core.js

2. Test locally using risa-cli.js

3. Validate against a real .r3d file

4. Move the logic into the MCP tools in index.js

5. Test again through Claude Desktop

The CLI exists specifically so parser development does not require Claude or MCP during iteration.

Developer Checks

Before committing changes, run:

node --check index.js
node --check risa-core.js
node --check risa-cli.js

Regression Tests

This project includes a modular regression test suite to protect the parser and write helpers from breaking during future development.

Run the full suite:

node tests\run-all.js

Current coverage:

• Parser

• Load ownership

• Geometry helpers

• QC engine

• Write helpers

• File I/O: section lookup, safe splicing, CRLF preservation, pre-save validation

• Adding node and distributed loads

• Every write tool, end to end through an MCP client, on LF and CRLF copies of tests/fixtures/sample.r3d (a synthetic model)

Technical Notes on the .r3d Format

Several non-obvious quirks in RISA's file format that this server handles, documented here for anyone extending it:

1. Fixed-width quoted fields. Labels, types, and section sizes are stored as quote-padded strings, e.g. "M14 ". A naive whitespace split breaks these into multiple phantom tokens. This server uses a quote-aware tokenizer that treats anything inside "..." (including internal spaces) as a single field.

2. Members reference nodes by position, not by label. In [.MEMBERS_MAIN_DATA], the i-node and j-node fields are 1-based indices into the order of the [NODES] list -- not the node label strings. For example, a member line containing 1 7 means the 1st node listed to the 7th node listed, which might resolve to N5 and N18. This server resolves those indices against an ordered node array.

3. Load section names. Point/nodal loads are stored under [NODE_LOADS], not [JOINT_LOADS]. Member distributed loads are stored under [DIRECT_DISTRIBUTED_LOADS], not [MEMBER_DISTRIBUTED_LOADS].

4. Load case IDs in load sections. The load case index stored in [NODE_LOADS], [DIRECT_DISTRIBUTED_LOADS], and [AREA_LOADS] entries is an internal RISA database ID, not the sequential 1-based index from [BASIC_LOAD_CASES]. When no name match is found, the tool labels the load case as LC{n}.

The member line format (after tokenizing) is:

Label, Type (e.g. "Wide Flange", "Tube", "Channel", "None"), Size (e.g. "W14X22", "HSS8X8X10"), iNodeIndex, jNodeIndex, ...

Roadmap

• Read and summarize any .r3d model

• List members with type, size, and resolved node connectivity

• List nodes with coordinates

• List load combinations

• Get raw file section by name

• Compare two models and summarize differences

• Export member schedule as CSV

• QC checker for common modeling issues

• Get steel material properties (Grade, E, Fy, Fu)

• Get boundary conditions with plain-English descriptions

• Get section sets and assigned sizes

• Summarize model for report in a single call (includes loads)

• Batch summarize all models in a project folder

• Get basic load cases with load type classification

• Find all members using a specific section size

• Get deflection limit rules (global and per-member)

• Modify member section sizes and save the updated model

• Clone a model with section, boundary condition, and load changes applied

• Material takeoff with AISC shape weights

• Length-based screen for unbraced length review

• Direct .xlsx export (member schedule and batch summary)

• Add new members (braces, posts, etc.) connecting existing or new nodes

• Export to SAF format (.xlsx) for import into SCIA, SOFiSTiK, AxisVM, and other SAF-compatible software

• Detect duplicate nodes (coordinate tolerance scan)

• Replace section size globally across a folder of models

• Diff two model versions (nodes, members, section sets, load combinations)

• Standalone CLI mode for parser testing

• Load ownership resolution using Basic Load Case counts

• Node load editing in cloned models

• Batch replace multiple section sizes in one model

• Batch QC folder export to Excel

• Export load summaries to Excel

• Move existing nodes

• Delete members

• Find connected members

• Get member connectivity at a node

• Copy members between existing nodes

• Split members

• Merge compatible members

• Mirror selected geometry

• Copy/translate selected geometry

• Shared geometry editing helpers in risa-core.js

• Modular regression test suite

Known Limitations

Current limitations:

• Area load editing is not supported.

• Generated transient/memberized loads are read but not regenerated.

• The server does not run RISA analysis.

• The server does not run RISA design checks.

• The server reads and modifies .r3d files only.

• Write operations should always be verified inside RISA-3D before engineering use.

• Load combinations are currently read but not modified.

Contributing

Pull requests are welcome. If you work with RISA-3D and have ideas for new tools, open an issue and let's discuss.

About

Built by Vibhanshu Mishra, PE -- Structural Engineer at AG&E Structural Engineers, Austin TX.

Specialising in steel and mission-critical structures. Building AI tools for a niche where none existed.