Skip to main content
Glama

RSAP MCP — Robot Structural Analysis ↔ Claude

MCP server cho Autodesk Robot Structural Analysis Professional 2027 — dùng với Claude hoặc Codex.

Mục lục / Contents


Related MCP server: AutoCAD MCP Server

Yêu cầu / Requirements

OS

Windows 10/11 (64-bit)

Robot

Robot Structural Analysis Professional 2027, đã cài & mở ít nhất một lần

Python

3.10+, 64-bit

uv

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Host

Claude Desktop hoặc Codex


Bước 1 — Cài đặt / Install

git clone https://github.com/nhantruong96/rsap-mcp.git
cd rsap-mcp
uv sync

Chạy lại uv sync sau mỗi git pull.

Kiểm tra (không cần Robot):

uv run python -m rsap_mcp --selfcheck
# -> [selfcheck] 35 tools registered ... OK

Tùy chọn thêm / optional extras:

uv sync --extra dev     # + ruff

Tùy chọn — chép .env.example thành .env rồi sửa RSAP_VISIBLE, RSAP_INTERACTIVE, RSAP_AUTO_CONNECT, RSAP_LOG_LEVEL, RSAP_LOG_FILE, RSAP_PROJECT_DIR.

Không có uv:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

Bước 2 — Đăng ký với Claude Desktop / Register with Claude Desktop

powershell -ExecutionPolicy Bypass -File .\scripts\register_claude_desktop.ps1

Hoặc sửa tay %APPDATA%\Claude\claude_desktop_config.json: chép một trong hai khối dưới đây, thay C:\path\to\rsap-mcp bằng đường dẫn thật (mẫu: config/claude_desktop_config.example.json).

A. Qua uv — khuyến nghị:

{
  "mcpServers": {
    "rsap": {
      "command": "uv",
      "args": ["--directory", "C:/path/to/rsap-mcp", "run", "rsap-mcp"]
    }
  }
}

B. Trỏ thẳng Python của venv — khi uv không có trong PATH của Claude Desktop:

{
  "mcpServers": {
    "rsap": {
      "command": "C:\\path\\to\\rsap-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "rsap_mcp"],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\rsap-mcp\\src",
        "RSAP_VISIBLE": "true",
        "RSAP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Sau khi sửa: thoát hẳn rồi mở lại Claude Desktop. Log: %APPDATA%\Claude\logs\mcp-server-rsap.log.


Bước 3 — Dùng thử / First run

Mở Claude Desktop và ra lệnh bằng lời:

"Kết nối Robot, tạo dự án khung 2D, dựng khung cổng nhịp 6 m cao 4 m bằng thép S235 IPE300, ngàm 2 chân, thêm trọng lượng bản thân và tải mái 10 kN/m, chạy tổ hợp ULS 1.35×TT+1.5×HT rồi cho biết phản lực chân cột và mô men lớn nhất ở xà."

"Connect to Robot, make a 2D frame, build a 6×4 m portal in S235 IPE300, fix both bases, add self-weight and a 10 kN/m roof load, run a 1.35G+1.5Q ULS combination, then tell me the base reactions and peak rafter moment."

Trình tự chuẩn / the workflow:

connect → new_project → add_nodes → add_bars → define_section/material → assign →
define_support → assign_support → add_load_case → add_*_load → add_combination →
calculate → bar_forces / node_displacement / node_reaction → save_project
  • Đơn vị: m, N, N·m.

  • Chuỗi chọn đối tượng: '1to10', '1 2 3', '1to20by2'.

  • Chờ lâu ở tool đầu tiên — Robot đang mở.


Dùng với Codex / Use with Codex

  1. Mở C:\Users\<YOU>\.codex\config.toml (macOS/Linux: ~/.codex/config.toml).

  2. Thêm khối sau, sửa đường dẫn (mẫu: config/codex_config.example.toml):

    [mcp_servers.rsap]
    enabled = true
    command = 'C:\path\to\rsap-mcp\.venv\Scripts\python.exe'
    args = ["-m", "rsap_mcp"]
    startup_timeout_sec = 30
    tool_timeout_sec = 600                      # rsap_calculate chạy lâu
    default_tools_approval_mode = "prompt"      # "auto" nếu không muốn hỏi từng tool
    
    [mcp_servers.rsap.env]
    RSAP_VISIBLE = "true"
    RSAP_INTERACTIVE = "true"
    RSAP_AUTO_CONNECT = "true"
    RSAP_LOG_LEVEL = "INFO"

    Hoặc thêm bằng một dòng lệnh / or add it with the CLI:

    codex mcp add rsap --env RSAP_VISIBLE=true --env RSAP_AUTO_CONNECT=true -- `
      "C:\path\to\rsap-mcp\.venv\Scripts\python.exe" -m rsap_mcp
  3. Kiểm tra: codex mcp list.

  4. Thoát hẳn và mở lại app Codex, gõ /mcp để thấy rsap và 35 tools.

Giới hạn tool: thêm enabled_tools = [...] hoặc disabled_tools = [...] vào khối [mcp_servers.rsap].


Kiểm thử bằng client rời / Test with the standalone client

uv run python client\test_client.py                # liệt kê tool qua MCP thật
uv run python client\test_client.py --call rsap_status
uv run python client\examples\01_portal_frame.py   # end-to-end (cần Robot)
uv run ruff check .                                # lint

Thêm công cụ mới / Add a new tool

  1. Mở module phù hợp trong src/rsap_mcp/tools/ (project_, modeling_, property_, support_, load_, analysis_, results_tools.py).

  2. Viết hàm bên trong register(mcp), gắn @mcp.tool() rồi @com_call, kèm type hints và docstring Google-style:

    def register(mcp):
        @mcp.tool()
        @com_call
        def rsap_count_objects() -> dict:
            """Return node and bar counts."""
            c = conn()
            return {"nodes": c.count(c.nodes), "bars": c.count(c.bars)}
  3. Gọi hằng RobotOM bằng tên qua const("I_..."), không ghi số trực tiếp.

  4. Trả về dict hoặc model Pydantic; lỗi thì raise.

  5. Không dùng print(); log qua config.py.

  6. Chạy uv run python -m rsap_mcp --selfcheck và uv run ruff check ..


Danh sách công cụ / Tool list

35 tool (tiền tố rsap_) và 3 resource. Dấu * = tham số bắt buộc.

Session & Project

Tool

Mô tả / Description

Tham số / Parameters

rsap_connect

Connect to (or launch) Autodesk Robot Structural Analysis Professional.

visible:boolean, interactive:boolean

rsap_status

Report connection status and a summary of the current Robot model.

(none)

rsap_new_project

Create a new, empty Robot project.

project_type:string

rsap_open_project

Open an existing Robot model from an absolute .rtd path.

path:string *

rsap_save_project

Save the current model. Pass a path to Save As, or omit to Save in place.

path:string/null

rsap_close_project

Close the current project (Robot itself stays open).

(none)

Modeling

Tool

Mô tả / Description

Tham số / Parameters

rsap_add_node

Create a single node at the given coordinates (metres).

x:number *, y:number *, z:number *, number:integer/null

rsap_add_nodes

Create many nodes at once.

nodes:array *

rsap_add_bar

Create a bar (beam/column) between two existing nodes, optionally assigning section/material.

start_node:integer *, end_node:integer *, number:integer/null, section:string/null, material:string/null

rsap_add_bars

Create many bars at once.

bars:array *

rsap_list_nodes

List nodes with their coordinates.

limit:integer

rsap_list_bars

List bars with their start/end node numbers.

limit:integer

rsap_delete_objects

Delete nodes or bars matching a selection string.

object_type:string *, selection:string *

Sections & Materials

Tool

Mô tả / Description

Tham số / Parameters

rsap_define_section

Define a bar section label by loading a profile from Robot's active database.

name:string *, db_section:string/null, material:string/null

rsap_define_material

Define a material label, either loaded from Robot's material database or from explicit properties.

name:string *, from_database:string/null, material_type:string/null, e:number/null, nu:number/null, ro:number/null, kirchoff:number/null

rsap_assign_section

Assign an existing section label to a set of bars.

section_name:string *, bars:string *

rsap_assign_material

Assign an existing material label to a set of bars.

material_name:string *, bars:string *

rsap_list_sections

List the names of section labels defined in the model.

(none)

Supports

Tool

Mô tả / Description

Tham số / Parameters

rsap_define_support

Define a support (boundary condition) label. True = restrained.

name:string *, ux:boolean, uy:boolean, uz:boolean, rx:boolean, ry:boolean, rz:boolean

rsap_assign_support

Assign an existing support label to a set of nodes.

support_name:string *, nodes:string *

Loads & Combinations

Tool

Mô tả / Description

Tham số / Parameters

rsap_add_load_case

Create a simple load case.

name:string *, nature:string, analysis:string, number:integer/null

rsap_add_self_weight

Add a self-weight (dead) load to a case.

case_number:integer *, direction:string, factor:number, selection:string

rsap_add_nodal_force

Add a nodal force/moment to a case (global axes).

case_number:integer *, nodes:string *, fx:number, fy:number, fz:number, cx:number, cy:number, cz:number

rsap_add_bar_uniform_load

Add a uniformly distributed load along bars.

case_number:integer *, bars:string *, px:number, py:number, pz:number, local:boolean, projected:boolean

rsap_add_bar_point_load

Add a concentrated (point) force/moment on bars.

case_number:integer *, bars:string *, fx:number, fy:number, fz:number, cx:number, cy:number, cz:number, position:number, relative:boolean, local:boolean

rsap_add_combination

Create a load combination from weighted load cases.

name:string *, factors:array *, combo_type:string, nature:string, number:integer/null

rsap_list_load_cases

List load cases and combinations in the model.

(none)

Analysis

Tool

Mô tả / Description

Tham số / Parameters

rsap_generate_mesh

Generate the finite-element mesh.

(none)

rsap_calculate

Run the structural analysis (solve the model).

(none)

rsap_calculation_status

Report whether analysis results are currently available.

(none)

Results

Tool

Mô tả / Description

Tham số / Parameters

rsap_bar_forces

Internal forces at a point along a bar (local axes).

bar:integer *, case:integer *, position:number

rsap_bar_force_envelope

Sample a bar along its length and return the extreme internal forces.

bar:integer *, case:integer *, samples:integer

rsap_node_displacement

Nodal displacement (global axes).

node:integer *, case:integer *

rsap_node_reaction

Support reaction at a node (global axes).

node:integer *, case:integer *

rsap_results_summary

Summarise results for a case: peak nodal displacement and peak bar moment.

case:integer *, max_nodes:integer, max_bars:integer

Resources

URI

Nội dung / Content

rsap://reference/enums

Bản đồ friendly → hằng RobotOM.

rsap://reference/sections

Hướng dẫn tiết diện & vật liệu.

rsap://reference/cheatsheet

Quy trình end-to-end.

Tham chiếu RobotOM COM API để mở rộng server: docs/RobotOM_API_Reference.md.


Xử lý sự cố / Troubleshooting

Triệu chứng / Symptom

Xử lý / Fix

Server không hiện trong Claude

Kiểm tra command/PYTHONPATH, khởi động lại Claude, xem mcp-server-rsap.log.

/mcp trong Codex không thấy rsap

Thoát hẳn & mở lại Codex; chạy codex mcp list; kiểm tra command trong config.toml.

constant 'I_...' not found

Mở Robot một lần để đăng ký type library; đối chiếu tên hằng trong enums.py.

Kết nối COM thất bại

Dùng Python 64-bit; kiểm tra Robot đã cài đúng bitness.

Giao thức hỏng ngay khi khởi động

Tìm thư viện đang in ra stdout; chuyển log sang stderr/file.

ModuleNotFoundError: mcp.server.fastmcp

Đang dùng mcp 2.x; gói đã ghim mcp[cli]<2 — chạy lại uv sync.

ModuleNotFoundError: mcp khi chạy client

Chạy qua venv: uv run python client\....

Could not read results

Chạy rsap_calculate() trước; kiểm tra số bar/node/case có tồn tại.

LoadFromDBase lỗi

Đặt đúng CSDL tiết diện/vật liệu trong Job Preferences (IPE300 cần catalog châu Âu).

Treo khi Calculate

Đóng hộp thoại đang chờ trong cửa sổ Robot.

Tool đầu tiên rất chậm / timeout

Robot đang khởi động — tăng tool_timeout_sec hoặc mở Robot sẵn.

Model gọi tool sai thứ tự

Nhắc trong prompt "làm tuần tự theo cheatsheet".


Cấu trúc thư mục / Repository layout

rsap-mcp/
├── src/rsap_mcp/          # MCP server (server.py, robot_app.py, com_utils.py,
│   │                      #   enums.py, config.py)
│   ├── tools/             # 35 tool rsap_* theo nhóm
│   ├── models/            # pydantic schemas
│   └── resources/         # rsap://reference/*
├── client/                # client MCP rời + examples
├── scripts/               # install / run / register (PowerShell)
├── config/                # claude_desktop_config.example.json, codex_config.example.toml
├── native/RsapHelper/     # DLL C# tùy chọn
├── docs/                  # RobotOM_API_Reference.md
├── pyproject.toml
└── uv.lock                # `uv sync` đọc file này

License

MIT. © 2026 PORTCOAST Taskforce.

Available Tools

35 tools
rsap_add_barA

Create a bar (beam/column) between two existing nodes, optionally assigning an existing section and/or material label.

Args: start_node: Start node number. end_node: End node number. number: Explicit bar number; auto-assigned if omitted. section: Name of an existing section label to assign (see rsap_define_section). material: Name of an existing material label to assign (see rsap_define_material).

Inputs: end_node (required), start_node (required), number, section, +1 more.

rsap_add_bar_point_loadA

Add a concentrated (point) force/moment on bars.

Args: case_number: Target load case number. bars: Bar selection text. fx, fy, fz: Forces (N). cx, cy, cz: Moments (N·m). position: Location along the bar. Relative (0–1) if relative=True, else metres from end A. relative: Treat 'position' as a 0–1 fraction of the bar length. local: Interpret forces in the bar's local axes.

Inputs: bars (required), case_number (required), cx, cy, +7 more.

rsap_add_barsB

Create many bars at once.

Args: bars: List of {start_node, end_node, number?, section?, material?} specs.

Inputs: bars (required).

rsap_add_bar_uniform_loadA

Add a uniformly distributed load along bars.

Args: case_number: Target load case number. bars: Bar selection text, e.g. '1to10'. px: Intensity along X (N/m). py: along Y (N/m). pz: along Z (N/m). local: Interpret px/py/pz in the bar's local axes (default global). projected: Apply as projected load.

Inputs: bars (required), case_number (required), px, py, +3 more.

rsap_add_combinationA

Create a load combination from weighted load cases.

Args: name: Combination name, e.g. 'ULS 1.35G + 1.5Q'. factors: List of {case, factor} terms, e.g. [{case:1, factor:1.35},{case:2, factor:1.5}]. combo_type: 'uls' or 'sls'. nature: Combination nature (usually 'permanent'). number: Explicit combination number; auto-assigned if omitted.

Inputs: name (required), factors (required), nature, number, +1 more.

rsap_add_load_caseB

Create a simple load case.

Args: name: Case name, e.g. 'Self-weight', 'Live load', 'Wind X'. nature: permanent/dead, live/exploitation, wind, snow, seismic, temperature, accidental. analysis: static_linear (default), static_nonlinear, modal. number: Explicit case number; auto-assigned if omitted.

Inputs: name (required), nature, number, analysis.

rsap_add_nodal_forceA

Add a nodal force/moment to a case (global axes).

Args: case_number: Target load case number. nodes: Node selection text, e.g. '5' or '5 6 7'. fx: Force X (N). fy: Force Y (N). fz: Force Z (N). cx: Moment X (N·m). cy: Moment Y (N·m). cz: Moment Z (N·m).

Inputs: nodes (required), case_number (required), cx, cy, +4 more.

rsap_add_nodeA

Create a single node at the given coordinates (metres).

Args: x: X coordinate (m). y: Y coordinate (m). z: Z coordinate (m, vertical). number: Explicit node number; auto-assigned (next free) if omitted.

Inputs: x (required), y (required), z (required), number.

rsap_add_nodesB

Create many nodes at once.

Args: nodes: List of {x, y, z, number?} node specifications (coordinates in m).

Inputs: nodes (required).

rsap_add_self_weightA

Add a self-weight (dead) load to a case.

Args: case_number: Target load case number. direction: Gravity direction: z- (default), z+, x-, x+, y-, y+. factor: Multiplier on self-weight (1.0 = full self-weight). selection: 'all' for the whole structure, or a bar selection like '1to20'.

Inputs: case_number (required), factor, direction, selection.

rsap_assign_materialA

Assign an existing material label to a set of bars.

Args: material_name: Name of a material label defined with rsap_define_material. bars: Robot selection text, e.g. '1to20' or '1 2 3'.

Inputs: bars (required), material_name (required).

rsap_assign_sectionA

Assign an existing section label to a set of bars.

Args: section_name: Name of a section label defined with rsap_define_section. bars: Robot selection text, e.g. '1to20' or '1 2 3'.

Inputs: bars (required), section_name (required).

rsap_assign_supportA

Assign an existing support label to a set of nodes.

Args: support_name: Name of a support label defined with rsap_define_support. nodes: Robot selection text, e.g. '1 4' or '1to4'.

Inputs: nodes (required), support_name (required).

rsap_bar_force_envelopeB

Sample a bar along its length and return the extreme internal forces.

Args: bar: Bar number. case: Load case or combination number. samples: Number of equally spaced sample points (>= 2).

Inputs: bar (required), case (required), samples.

rsap_bar_forcesA

Internal forces at a point along a bar (local axes).

Args: bar: Bar number. case: Load case or combination number. position: Relative position along the bar, 0.0 (start) to 1.0 (end).

Inputs: bar (required), case (required), position. Returns: Internal forces at a point along a bar (local axes).

rsap_calculateA

Run the structural analysis (solve the model).

This blocks until Robot finishes calculating. After it returns, use the results tools (rsap_bar_forces, rsap_node_displacement, rsap_node_reaction).

Inputs: no named parameters.

rsap_calculation_statusA

Report whether analysis results are currently available.

Inputs: no named parameters.

rsap_close_projectA

Close the current project (Robot itself stays open).

Inputs: no named parameters.

rsap_connectA

Connect to (or launch) Autodesk Robot Structural Analysis Professional.

Call this once before other tools, unless auto-connect is enabled. If Robot is already open it attaches to it; otherwise it starts Robot.

Args: visible: Show the Robot application window. interactive: Keep Robot interactive so its GUI refreshes as the model changes.

Inputs: visible, interactive.

rsap_define_materialA

Define a material label, either loaded from Robot's material database or from explicit elastic properties.

Args: name: Name for the new material label. from_database: Load a named material from Robot's database (e.g. 'S235', 'C30/37'). If given, the explicit properties below are ignored. material_type: One of steel, concrete, timber, aluminium, other. e: Young's modulus E (Pa). nu: Poisson's ratio (dimensionless). ro: Unit WEIGHT density (N/m^3) — Robot's RO is a weight density, not mass. kirchoff: Shear modulus G (Pa) — stored in Robot's 'Kirchoff' property.

Inputs: name (required), e, nu, ro, +3 more.

rsap_define_sectionA

Define a bar section label by loading a profile from Robot's active section database (e.g. an I-profile, HEA, IPE, tube...).

The section database must already be active in Robot's job preferences and must contain the requested profile name.

Args: name: Name to give the new section label (often the profile name itself). db_section: Profile name to load from the section database. Defaults to name. material: Optional material label name to attach to the section.

Inputs: name (required), material, db_section.

rsap_define_supportA

Define a support (boundary condition) label. True = restrained.

Common presets: a pinned support is ux=uy=uz=True, rx=ry=rz=False; a fully fixed support is all True; a roller restrains only the relevant translation.

Args: name: Name for the support label (e.g. 'pinned', 'fixed'). ux: Restrain translation X. uy: Restrain translation Y. uz: Restrain translation Z. rx: Restrain rotation X. ry: Restrain rotation Y. rz: Restrain rotation Z.

Inputs: name (required), rx, ry, rz, +3 more.

rsap_delete_objectsA

Delete nodes or bars matching a selection string.

Args: object_type: 'node' or 'bar'. selection: Robot selection text, e.g. '1to10 15' or '1 2 3'.

Inputs: selection (required), object_type (required).

rsap_generate_meshA

Generate the finite-element mesh.

Note: FE meshing only applies to surface/panel (shell) models, and Robot generates it automatically when you run rsap_calculate(). Pure bar/frame models do not need an explicit mesh, so for them this is a no-op.

Inputs: no named parameters.

rsap_list_barsA

List bars with their start/end node numbers.

Args: limit: Maximum number of bars to return.

Inputs: limit.

rsap_list_load_casesA

List load cases and combinations in the model.

Inputs: no named parameters.

rsap_list_nodesA

List nodes with their coordinates.

Args: limit: Maximum number of nodes to return.

Inputs: limit.

rsap_list_sectionsA

List the names of section labels defined in the model.

Inputs: no named parameters.

rsap_new_projectA

Create a new, empty Robot project.

Args: project_type: One of shell, frame_3d, frame_2d, truss_3d, truss_2d, plate, grillage.

Inputs: project_type.

rsap_node_displacementB

Nodal displacement (global axes).

Args: node: Node number. case: Load case or combination number.

Inputs: case (required), node (required). Returns: Nodal displacement (global axes).

rsap_node_reactionA

Support reaction at a node (global axes).

Args: node: Node number (must be a supported node). case: Load case or combination number.

Inputs: case (required), node (required). Returns: Support reaction at a node (global axes).

rsap_open_projectA

Open an existing Robot model from an absolute .rtd path.

Args: path: Absolute path to the .rtd file on the machine running Robot.

Inputs: path (required).

rsap_results_summaryA

Summarise results for a case: peak nodal displacement and peak bar moment.

Args: case: Load case or combination number. max_nodes: Cap on nodes scanned (largest |Uz|). max_bars: Cap on bars scanned (largest |My| at mid-span).

Inputs: case (required), max_bars, max_nodes.

rsap_save_projectA

Save the current model. Pass a path to Save As, or omit to Save in place.

Args: path: Absolute .rtd path to save to (Save As), or None to overwrite the currently open file.

Inputs: path.

rsap_statusA

Report connection status and a summary of the current Robot model.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 35 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: define/create/assign/query are cleanly separated, and singular vs. bulk variants (e.g., add_node vs. add_nodes) are clearly named. Even similar results tools (bar_forces vs. bar_force_envelope) differ in purpose and are unambiguous.

    Naming Consistency3/5

    All tools share the 'rsap_' prefix and snake_case, but the verb-noun pattern is not universal: results tools (bar_forces, node_displacement, node_reaction, results_summary) omit the verb, while most others use verb_first (add_, list_, define_). This mixed convention is readable but not fully predictable.

    Tool Count3/5

    35 tools is above the typical well-scoped range, but the domain (full structural analysis lifecycle) justifies the breadth. The count feels heavy yet each tool covers a distinct need; a smaller set would require awkward multi-purpose tools.

    Completeness4/5

    The set covers the core workflow: project management, geometry (nodes/bars), properties, supports, loads, analysis, and results. Notable gaps exist for shell/plate modeling (despite project types including shell) and there are no update/edit tools for existing objects, but the main frame/bar analysis pathway is complete.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects Claude to a running Autodesk Civil 3D instance via COM automation to perform drawing, surface, alignment, COGO point, line, and corridor operations.
      13
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables programmatic control of AutoCAD through COM automation, allowing natural language commands to create structures, manage layers, and manipulate entities via MCP clients like Claude.
      70
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables users to control CSI ETABS structural engineering software through Claude, allowing model creation, status checks, and engineering checks via COM automation.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to directly control Midas Civil NX for bridge structural analysis, allowing users to model, apply loads, and perform analysis through natural language descriptions.
      4
      MIT