beam-analysis-mcp

A lightweight MCP (Model Context Protocol) server for linear-static structural analysis of bridges and building frames, written in Node.js with no heavy dependencies.

It gives an AI client (Claude Desktop, Claude Code, Cursor, ...) tools to:

• Build 3D beam/truss models (nodes, members, sections, materials, supports, loads) or generate complete structures from parametric typology presets (girder bridges, Pratt/Howe/Warren truss bridges, arch bridges, cable-stayed bridges, portal frames, moment frames, 3D braced buildings, roof trusses).

• Analyze them with two engines:

  • beam — built-in 3D direct-stiffness frame solver (pure JavaScript, instant). Euler-Bernoulli elements with consistent fixed-end forces and exact in-span deflection/moment recovery — one element per member is enough.

  • calculix — writes a CalculiX input deck (B32R beam elements), runs ccx, and parses displacements/reactions. Use engine: "both" to cross-check the two solvers.

• Export to FreeCAD — builds a solid 3D model of the structure and saves a .FCStd document you can open and inspect in FreeCAD.

• Get member force envelopes (N, V, M, T), stresses, and utilization (σ/fy), reactions, and displacements.

No CalculiX install needed if you have FreeCAD: FreeCAD bundles ccx with its FEM workbench, and this server auto-detects it (e.g. C:\Program Files\FreeCAD 1.1\bin\ccx.exe).

Requirements

• Node.js ≥ 18

• Optional: FreeCAD (provides both freecadcmd for export and the bundled CalculiX solver)

• Optional: standalone CalculiX (ccx) if you don't use FreeCAD

Related MCP server: FreeCAD Robust MCP Server

Install & run

git clone https://github.com/StructuralWizard/beam-analysis-mcp.git
cd beam-analysis-mcp
npm install
npm test          # closed-form validation + MCP e2e + CalculiX cross-check
npm run typologies  # analyze 10 bridge/building typologies with both engines

Claude Desktop / Claude Code configuration

Add to claude_desktop_config.json (or .mcp.json for Claude Code):

{
  "mcpServers": {
    "beam-analysis": {
      "command": "node",
      "args": ["C:/path/to/beam-analysis-mcp/src/server.js"]
    }
  }
}

Optional environment variables:

Tools

Structure presets

Example conversation with an MCP client:

"Generate a 3-span continuous girder bridge (30 m + 40 m + 30 m), analyze it with both engines, and export it to FreeCAD."

which maps to generate_structure {preset: "beam_bridge", params: {spans: [30,40,30]}} → analyze {engine: "both"} → export_freecad.

Conventions

• Units: SI — meters, Newtons, Pascals, kg/m³. Downward loads are negative fz/wz.

• Axes: global +Z is up. Member local x runs along the member; for non-vertical members local z lies in the vertical plane, so section depth h resists gravity bending (strong axis = Iy).

• Supports: fixed, pinned, roller (uz), roller-yz (bridge sliding bearing), planar-xz (out-of-plane restraint for 2D models), or a custom 6-flag string like "111100" (ux,uy,uz,rx,ry,rz).

• Member types: beam (6-DOF frame element) or truss (axial only — braces, cables, truss webs).

Validation

Full test documentation — every test case, the theory it checks against, tolerances, and the investigation notes behind the cross-engine differences — is in docs/VALIDATION.md.

An illustrated per-structure validation report for all 10 typologies — geometry/supports/loads figures, CalculiX meshes, load cases with superposition checks, deformed shapes (built-in vs CalculiX overlay), moment/shear/axial diagrams, stress & strain maps, CalculiX von Mises fields parsed from .frd, and 35 analytical hand-calculation checks — is in docs/validation/.

npm test checks the solver against closed-form solutions:

• Simply supported beam under UDL: 5wL⁴/384EI deflection and wL²/8 moment (exact to 1e-6)

• Cantilever tip load / UDL: PL³/3EI, wL⁴/8EI, fixed-end moments

• Two-bar truss axial force P/(2 sin θ)

• Equilibrium (ΣR = ΣF) on every generator preset

• Cross-validation against CalculiX (skipped automatically if ccx is not installed)

npm run typologies builds and analyzes 10 typologies end-to-end and prints a built-in vs CalculiX comparison table. Results on the reference machine (FreeCAD 1.1 bundled CalculiX 2.22, Windows 11):

* Expected: the tower mixes several cross-sections, and CalculiX models joints between members of different sections as flexible "knots" (see Limitations). Re-run with uniform sections and the two engines agree within 6%.

Limitations

• Linear static only: no buckling, no dynamics, no P-Δ, no nonlinear cable sag (stays are modeled as linear truss members that can also take compression).

• The two engines answer slightly different questions: the built-in solver assumes ideal rigid joints (classic beam theory), while CalculiX expands beams into solid elements and models joints between members of different sections as "knots", which are more flexible. Agreement is sub-1% on determinate structures and within a few % on frames with uniform sections, but expect larger differences (which ccx reports as a note) on tall 3D frames mixing many sections.

• CalculiX backend reports displacements and reactions; member force envelopes come from the built-in engine.

• I-sections and generic sections are mapped to an equivalent rectangle in the CalculiX deck (ccx beam sections support RECT/CIRC/PIPE/BOX only).

• Results are for preliminary/educational analysis — not a substitute for design verification by a qualified engineer.

License

MIT