csibridge-mcp
csibridge-mcp lets an AI assistant drive a live Windows CSiBridge session over MCP, to inspect, build/edit, analyze, and read models.
Check attachment/status, attach to a specific instance, or launch CSiBridge.
Call any CSiBridge API function by documented path, singly or in ordered batches.
Search/describe the installed API and inspect enum values from its type library.
Open, save, or create models; run analyses; wait for long-running jobs.
List, read, and edit database tables covering model definitions (including bridge layout lines, deck sections, bridge objects) and analysis/design results.
Work against the running CSiBridge session so changes appear on screen.
Connect locally via stdio (Claude Code, VS Code Copilot, Visual Studio) or remotely over HTTPS with per-person tokens (e.g., Microsoft 365 Copilot).
Develop and test off Windows using the mock backend.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@csibridge-mcp what's the maximum deflection in the open CSiBridge model?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
csibridge-mcp
An MCP server that lets an AI assistant drive a running CSiBridge: build and edit models, run analyses, and read results, by calling CSiBridge's own API. It works with any client that speaks the Model Context Protocol: Claude Code, GitHub Copilot in VS Code or Visual Studio, and, over HTTP, remote clients such as Microsoft 365 Copilot.
How it works
CSiBridge exposes its API through COM, which exists only on Windows. So the server runs on the same Windows machine as CSiBridge, attaches to the CSiBridge instance you already have open, and works in that live session: you see every change on screen as it happens.
MCP client --stdio or HTTPS--> csibridge-mcp --COM (comtypes)--> CSiBridgeRather than wrapping a hand-picked subset of the API, the server exposes all of it:
call/batchinvoke any API function by its documented path, such asSapModel.FrameObj.AddByCoord.api_search/api_describe/api_enumread function signatures and enum values from the type library of the CSiBridge version that is actually installed, so the assistant checks a signature instead of guessing it. This includes the parametric Bridge Modeler API (SapModel.BridgeModeler_1, CSiBridge v25 and later).list_tables/get_table/edit_tableread and edit CSiBridge's database tables, which cover model definitions (including bridge layout lines, deck sections and bridge objects) and all analysis and design results.
Because CSiBridge cannot run on macOS or Linux, the server also has a mock backend: a small fake of the API, shaped like the real COM wrappers, that makes it possible to develop and test here.
Related MCP server: OpenSTAAD MCP Server
Setup on Windows
Requirements: CSiBridge installed and licensed, and an MCP client. Then pick one of two ways to get the server onto the machine.
Option A: the portable zip (nothing to install)
For locked-down or non-technical machines. The zip bundles the official embeddable Python, so it needs no Python, uv, git or admin rights.
Download
csibridge-mcp-portable-win64.zipfrom the releases page (every CI run also produces it as a build artifact) and unzip it anywhere, for example in Documents.Start CSiBridge and open a model (any model; the database-table check is skipped without one), then double-click
Self-test.cmd. It attaches to CSiBridge, reads the API's type library, makes a few read-only calls and prints a pass/fail report. It changes nothing in your model.Connect your client (see below). The server command is the
python\python.exeinside the folder with the arguments-m csibridge_mcp;Register with Claude Code.cmddoes this for Claude Code.
Option B: from source with uv
Needs uv (winget install astral-sh.uv). Open a new terminal
afterwards, and restart your MCP client, so that they find uv on the PATH.
git clone https://github.com/austinulfers/csibridge-mcp.git
cd csibridge-mcp
uv sync
uv run csibridge-mcp selftestThe server command is then uv run --directory C:\path\to\csibridge-mcp csibridge-mcp.
Connecting a client on the same machine
Claude Code
claude mcp add --scope user csibridge -- uv run --directory C:\path\to\csibridge-mcp csibridge-mcp(Or the portable folder's python\python.exe -m csibridge_mcp in place of the uv run ... part.)
Run /mcp inside Claude Code to confirm csibridge is connected.
VS Code (GitHub Copilot agent mode) — add the server with the "MCP: Add Server" command, or
put this in .vscode/mcp.json in your workspace:
{
"servers": {
"csibridge": {
"type": "stdio",
"command": "C:\\path\\to\\csibridge-mcp\\python\\python.exe",
"args": ["-m", "csibridge_mcp"]
}
}
}Visual Studio 2022 (17.14 or later) — the same servers block in a .mcp.json next to your
solution.
Then ask the assistant something like "What model is open in CSiBridge?"
Notes:
CSiBridge and the MCP client must run as the same Windows user at the same elevation (both normal, or both "as administrator"); otherwise the running instance cannot be found.
The server attaches to a running CSiBridge. It only starts CSiBridge when asked to (
connectwithmode="launch"); pass--no-launchto forbid that.The first call after installing is slow, because comtypes generates Python wrappers for the whole API once and caches them.
Python must be 64-bit, like CSiBridge. The portable zip and uv's default both are.
--helper-progidand--progidselect a different CSI API library or product object. The defaults areCSiAPIv1.HelperandCSI.CSiBridge.API.SapObject.
Remote access over HTTP (Microsoft 365 Copilot, online agents)
Clients that run in the cloud cannot start a program on your PC, so for them the server can be served over HTTP instead of stdio. Access is locked down with per-person tokens: the server refuses every request that does not carry a valid one, tokens are issued and revoked by whoever hosts the server, and each request is logged under the name the token was issued to.
Create a token for each person (or client) allowed in. The token is shown once; it is stored hashed in
~/.csibridge-mcp/tokens.json.uv run csibridge-mcp token add "Jane Doe"(
token listandtoken revoke "Jane Doe"manage them; revoking takes effect immediately on a running server. The portable folder hasAdd access token.cmdfor this.)Start the server over HTTP. With CSiBridge open:
uv run csibridge-mcp serve --http(Portable folder:
Start HTTP server.cmd.) By default it listens only on this machine, athttp://localhost:8765/mcp, and refuses to start if no tokens exist.Make it reachable over HTTPS — never expose it as plain HTTP. Any of these work:
A tunnel, which also handles certificates and firewalls:
cloudflared tunnel --url http://localhost:8765prints a publichttps://…address.A reverse proxy (IIS, Caddy, nginx) that terminates TLS and forwards to
localhost:8765.Direct, if you have a certificate:
serve --http --host 0.0.0.0 --tls-cert cert.pem --tls-key key.pem.
Point the client at
https://<your address>/mcpwith the token as a header, eitherAuthorization: Bearer <token>orX-API-Key: <token>:Microsoft 365 Copilot — in Copilot Studio, add a tool of type Model Context Protocol with that URL, authentication API key, sent in the
X-API-Keyheader. Share the resulting agent only with the people who should have it: that, plus the token, is the lock-down.Claude Code (from another machine):
claude mcp add --transport http csibridge https://<your address>/mcp --header "Authorization: Bearer <token>"VS Code:
"type": "http", "url": "https://<your address>/mcp", "headers": {"X-API-Key": "<token>"}.
Things to understand before sharing a token:
A token gives full use of the CSiBridge session on the hosting machine, including saving files there as the hosting user. Issue tokens only to people you would let sit at that computer.
Everyone with a token works in the same CSiBridge session and model. Calls run one at a time.
Claude.ai and ChatGPT custom connectors require OAuth sign-in rather than a static token, so they cannot use this server yet.
Tools
Tool | Purpose |
| Whether CSiBridge is attached, the open model, units, lock state, anything still running |
| Attach to a specific instance, re-attach, or launch CSiBridge |
| Call any API function by path |
| Run many calls in one round trip |
| Find functions by name; returns full signatures |
| List an interface's functions, or show one function's exact signature |
| List the values of an enum such as |
| Model files |
| Run the analysis |
| Keep waiting for a long operation |
| Database tables: definitions and results |
Conventions worth knowing:
A call returns
{"ret": ..., "outputs": {...}, "ok": ...}.outputsholds the function'srefparameters by name. For most functionsretis a status code where 0 means success, andokis false when it is nonzero.refparameters can be left out of a call, and arguments can be given by name.An operation that outlasts its
wait_seconds(an analysis, typically) returns{"pending": true, "job_id": ...}and keeps running;job_waitcollects the result.Calls run one at a time, in order, because the CSI API is not re-entrant.
A few failures make CSiBridge show a message box even when driven through the API (opening a file that does not exist, for one), and the call waits until someone closes it on screen. While that happens, pending results and
statusquote the dialog underdialogs, so the assistant can ask you to close it.open_modelchecks that the file exists first for this reason.Enum arguments can be given by name as CSI's documentation writes them, e.g.
"eMatType.Concrete".The server sends clients a short set of usage instructions (conventions like the ones above). Clients that do not pass server instructions to the model still get the essentials, which are repeated in each tool's description.
The instructions also cover CSiBridge behaviour found while building real models: result tables only report the load cases selected for display (
get_tablesays so when none are), tables that refer to each other must be edited together, cable forces are in the frame forces table, and the 3-D view of a model built from general objects needsView.RefreshWindowto repaint.
Developing on macOS or Linux
uv sync
uv run pytest # the test suite, against the mock backend
uv run csibridge-mcp selftest --mock # the same report the Windows self-test prints
uv run csibridge-mcp serve --http --mock --token csib_dev # the HTTP transport, locallyThis folder carries a csibridge-mock server entry for Claude Code (.mcp.json) and for VS Code
(.vscode/mcp.json): the real MCP server running on the mock backend, so the tools can be tried
in either client without Windows.
The mock (src/csibridge_mcp/mock_csi.py) implements a few dozen functions: enough to build a small
frame model, "analyse" it and read tables. Its numbers are placeholders, not structural results.
Code layout, in src/csibridge_mcp/:
File | Role |
| The MCP tools |
| Owns the CSiBridge connection; runs requests one at a time on a worker thread; the real (COM) and mock backends; the self-test |
| Reads function signatures from the type library; converts arguments and labels results |
| Access tokens and the auth layer for the HTTP transport |
| The fake API used off Windows |
| Command line entry point |
The portable zip is built by scripts/build-portable.ps1 (launchers in scripts/portable/); CI
(.github/workflows/ci.yml) runs the tests on Windows, macOS and Linux, builds the zip on every
push, and attaches it to the release for tags named v*.
What has and has not been verified
This was developed on a Mac, where CSiBridge cannot run.
Verified: the MCP server and every tool, end to end over stdio and over HTTP (including the token check), against the mock backend (
uv run pytest).Verified: the assumptions the real backend makes about comtypes, by running the introspection and result-labelling code against comtypes' own member-spec and calling-convention code (
tests/test_comtypes_contract.py). CI on Windows additionally checks that the COM path gets as far as looking for CSiBridge and reports its absence cleanly.Not yet verified: anything against a real CSiBridge. The COM backend in
engine.pyfollows CSI's published Python example and comtypes' source, but it has never been executed against the program. The three table tools also rely on the argument order of theSapModel.DatabaseTablesfunctions as CSI documents them.
So the first run on a machine with CSiBridge is the real test. Run the self-test there first; its report shows which layer fails, if any.
License
Functional Source License 1.1, MIT future license (FSL-1.1-MIT). You may use, modify and share it freely, including inside a company and for paid engineering work; what you may not do is offer it to others as a competing commercial product or service. Each version becomes MIT-licensed two years after its release.
Available Tools
15 toolsapi_describeARead-only
Describe part of the CSiBridge API, read from the installed version's type library.
Args: path: A function path ("SapModel.FrameObj.AddByCoord") for its exact parameters, an interface path ("SapModel.FrameObj") to list its functions, or empty for the tree of all interfaces. filter: When listing an interface, only show functions whose name contains this text.
Inputs: path, filter. Returns: result
api_enumARead-only
List the values of an API enum such as eUnits, eMatType or eLoadPatternType.
Give an enum name, or part of an enum or member name to find it. Empty lists all enums.
Inputs: name. Returns: result
api_searchARead-only
Search the installed CSiBridge API for functions by name.
Matches every word of the query against function paths and parameter names, and returns full signatures, e.g. query "frame distributed load" or "BridgeModeler span".
Inputs: query (required), limit. Returns: result
batchA
Run many API calls in order in one round trip.
Use this to build or query a model efficiently (for example adding dozens of objects).
Args:
calls: [{"method": "...", "args": [...], "kwargs": {...}}, ...], each with the same
meaning as the call tool.
stop_on_error: Stop at the first call that fails (default) rather than continuing.
wait_seconds: How long to wait before returning a pending job_id instead.
Inputs: calls (required), wait_seconds, stop_on_error. Returns: result
callA
Call any CSiBridge API function by its documented path.
Returns {"ret": return value, "outputs": {ref parameter: value}, "ok": bool}. For most
functions ret is a status code and 0 means success. Check a function's signature with
api_describe or api_search before calling it for the first time.
Args:
method: The function path, e.g. "SapModel.FrameObj.AddByCoord".
args: Input arguments in signature order. Trailing optional and ref parameters may
be left off. An object of name: value is also accepted.
kwargs: Input arguments by parameter name, instead of or after positional ones.
wait_seconds: How long to wait before returning a pending job_id instead.
Inputs: method (required), args, kwargs, wait_seconds. Returns: result
connectA
Attach to a running CSiBridge, or start one.
The other tools attach to a running CSiBridge automatically, so this is only needed to start CSiBridge (mode="launch"), to choose between several running instances (pid), or to re-attach after CSiBridge was restarted.
Args: mode: "attach" to use a running instance, "launch" to start a new one. pid: With "attach", the process id of the instance to use. program_path: With "launch", the full path of a specific CSiBridge.exe. Defaults to the latest installed version.
Inputs: pid, mode, program_path. Returns: result
edit_tableADestructive
Replace the contents of an editable database table (CSiBridge's interactive database editing).
The rows given become the table's entire contents: records left out are removed from the model. So read the table with get_table(for_editing=True), change what is needed, and send every row back. The model must be unlocked for most tables. Returns CSiBridge's import log.
Args:
table_key: The table's key, from list_tables.
fields: Field keys, in the order used by each row.
rows: The records, each a list of values in fields order or an object keyed by field.
table_version: The table_version returned by get_table(for_editing=True). Looked up if omitted.
apply: Apply the edit to the model now. With false the edit is only staged, to be
applied together with other tables by a later edit_table call.
Inputs: rows (required), fields (required), table_key (required), apply, +1 more. Returns: result
get_tableARead-only
Read a CSiBridge database table as {"fields": [...], "rows": [[...], ...]}.
Works for model definition tables and, after an analysis, result tables. All values are text, in the model's present units.
Args: table_key: The table's key, from list_tables. fields: Only these fields. Default: all fields. group: Only objects in this group. Default: all objects. where: Only rows whose fields equal these values, e.g. {"OutputCase": "DEAD"}. limit: Maximum number of rows to return. offset: Number of matching rows to skip, for paging. for_editing: Read the table in the form edit_table expects (all fields, plus the table_version to pass back). load_cases: For result tables, the load cases to report. load_combos: For result tables, the load combinations to report. load_patterns: For result tables, the load patterns to report.
Inputs: table_key (required), group, limit, where, +6 more. Returns: result
job_waitBRead-only
Wait for a pending operation (one that returned a job_id) and return its result.
Inputs: job_id (required), wait_seconds. Returns: result
list_tablesARead-only
List CSiBridge database tables: model definitions and analysis/design results.
Each entry has the table key (used by get_table) and its import_type: 0 = read-only, 1 = editable only by file import, 2 = editable with edit_table while the model is unlocked, 3 = editable with edit_table at any time.
Args: filter: Only tables whose key contains every word, e.g. "bridge section" or "joint". include_empty: Also list tables that have no data in the current model. limit: Maximum number of tables to return.
Inputs: limit, filter, include_empty. Returns: result
new_modelADestructive
Start a new blank model, replacing the model currently open.
Unsaved changes to the current model are lost, so save it first if they matter.
Args: units: Present units for the new model, one of: lb_in_F, lb_ft_F, kip_in_F, kip_ft_F, kN_mm_C, kN_m_C, kgf_mm_C, kgf_m_C, N_mm_C, N_m_C, Ton_mm_C, Ton_m_C, kN_cm_C, kgf_cm_C, N_cm_C, Ton_cm_C.
Inputs: units. Returns: result
open_modelADestructive
Open a CSiBridge model file (.bdb), replacing the model currently open.
Unsaved changes to the current model are lost, so save it first if they matter.
Args: path: Full Windows path of the model on the machine running CSiBridge.
Inputs: path (required). Returns: result
run_analysisA
Run the analysis of the open model.
The model must already have been saved to a file. Running locks the model. Large models take a while: if this returns pending, keep waiting with job_wait.
Inputs: wait_seconds. Returns: result
save_modelA
Save the open model.
Args: path: Full Windows path (.bdb) to save as. Empty saves to the model's current file, which fails if the model has never been saved.
Inputs: path. Returns: result
statusARead-only
Show whether CSiBridge is attached and what is open in it.
Reports the program version, the open model file, present units, whether the model is locked, and whether a long operation is still running. Call this first.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools target clearly distinct actions (status vs connect, list/get/edit_table, call vs batch, job_wait). The three discovery tools api_search/api_describe/api_enum overlap somewhat in intent, and the generic `call` tool conceptually overlaps with many specific tools, but descriptions differentiate them reasonably well.
Predominantly consistent snake_case with verb_noun or noun_action patterns (list_tables, get_table, edit_table, run_analysis, open_model, save_model, api_search). A few single-word tools (status, connect, call, batch) deviate slightly but remain clear and idiomatic.
15 tools is well within a healthy range for a complex bridge-engineering API. Each tool earns its place: lifecycle (new/open/save), execution (run_analysis/job_wait), table I/O (list/get/edit), discovery (api_*), and generic escape hatches (call/batch).
Covers connection, model lifecycle, analysis, table read/write, discovery, and arbitrary API calls plus batching, giving near-complete coverage via the generic `call`. Minor gaps like closing/disconnecting a model or instance explicitly are absent but workable around.
Maintenance
Related MCP Connectors
Build, check and report on MIDAS CIVIL NX bridge models and design tendons, with MIDAS IT plugins.
Connect your AI assistant to Blender for 3D modeling, Geometry Nodes, materials, lighting, animation, rendering and export. Inspect real scenes and viewport images, refine the result and restore checkpoints. OAuth connects your chat to Blender Bridge Desktop on an online Windows 10/11 x64 computer running Blender 4.2+. The chat can run on another device. Requires an active Blender Bridge account; 7-day trial available. AI model access is separate.
Structural FEM for AI agents: frames, plates, buckling, seismic and Eurocode checks, solved locally.
Kaiva Bridge turns your API, database or documents into a managed MCP server for Claude, ChatGPT, Cursor and VS Code. Point it at an OpenAPI or Swagger spec, an API docs link, a cURL command, a Postman collection, a GraphQL endpoint, Postgres, MySQL, MariaDB or SQL Server, spreadsheets, PDFs and other documents, or an MCP server you already run. Bridge reads the source and proposes tools, and you choose which ones your AI client sees. No code to write and nothing to run. Connect this server and your agent does the setup for you: it lists your servers, shows one, drafts a new server from an OpenAPI spec, and refreshes a server's tools when its API changes. Free plan: 10 servers and 200,000 tool calls a month, no credit card. Pricing: https://kaiv.ai/bridge/pricing Security: https://kaiv.ai/bridge/security Docs: https://kaiv.ai/bridge/docs
Related MCP Servers
- AlicenseAqualityDmaintenanceConnects AI assistants to CSI ETABS for structural engineering tasks, enabling model creation, analysis, design, and seismic checks via the COM API.6910MIT
- AlicenseAqualityDmaintenanceEnables AI agents to interact with Bentley STAAD.Pro models for tasks like load case definition, data extraction, and property setting, running locally with multi-instance support and no cloud dependency.5MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to interact with bridge structural analysis software for modeling, construction stages, and code checking.151Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI coding assistants to directly control CSI ETABS for structural and seismic analysis, including model inspection, material/section definition, frame generation, solver execution, and result extraction through natural language.2MIT