openmdao-mcp
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., "@openmdao-mcp Build the Sellar problem and run the model, then optimize with SLSQP"
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.
openmdao-mcp
openmdao-mcp is a domain-agnostic Model Context Protocol server for
OpenMDAO 3.45. It builds om.Problem instances from
declarative, validated specifications (components, nested groups, coupling
solvers, design variables, drivers) instead of hard-coded model topologies,
and it has no dependency on any discipline-specific analysis code.
It targets conceptual-design MDAO of the kind used in rotorcraft sizing:
coupled feedback loops converged by NonlinearBlockGS or Newton, black-box
command-line solvers, Latin-hypercube seed generation, finite-difference noise
diagnostics, and multi-start SLSQP. Development happens on Windows; production
runs on headless Rocky Linux 9.8.
REFACTOR_PLAN.md records the design, the full schema
catalogue, and the implementation history.
Quickstart
Requires Python 3.12+. Dependencies go into a local .venv with pip.
Windows:
python -m venv .venv
.\.venv\Scripts\pip.exe install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytestLinux:
python3.12 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytestRun the end-to-end example (Sellar problem: coupled loop, scaled SLSQP, active constraints):
PYTHONPATH=src python examples/client/sellar_mdao_workflow.pyRelated MCP server: JCGEAgentInterface
Running the server
Local use over stdio (the default transport):
openmdao-mcp --transport stdioRemote use over streamable HTTP:
openmdao-mcp --transport streamable-http --host 127.0.0.1 --port 8765 --allowed-commands /opt/solvers/bin/rotor_perfOption | Meaning |
| Default |
| HTTP only. |
| Problem specs, recordings and external-code runs. Default |
| Comma-separated executable paths or names that |
| Logs always go to stderr. |
The server has no built-in authentication. Keep --host 127.0.0.1 and put a
reverse proxy that authenticates clients in front of it.
Tools
All 21 tools validate their arguments with Pydantic v2 and answer with a JSON
object. Failures come back in-band as {"error": {"type", "message", "details"}};
a failed evaluation (om.AnalysisError) is reported as success: false, never
as an unhandled exception.
Group | Tools |
Health |
|
Problems |
|
Variables |
|
Solvers and drivers |
|
Runs |
|
Derivatives |
|
Observability |
|
A typical session:
create_problemwith aProblemSpec: independent variables,exec_compequations (checked against an AST whitelist),external_codeblack boxes (template in, run in an isolatedeval_<uuid>directory, JSONPath/regex out),metamodelsurrogates, and nested groups with their own solvers.run_modelto converge the coupled loop at the baseline.configure_optimization: design variables (gradient-based optimizers requireref/ref0orscaler), objective, constraints, driver.check_totals_sweepbefore SLSQP: finite-difference totals at several steps expose black-box noise and recommend a step forconfigure_approx_totals.run_doe(LHS viascipy.stats.qmc, full factorial viaitertools.product, both fed toListGenerator),run_driver, orrun_multistart(LHS, keep the best feasible seeds, normalized SLSQP from each, optionally inspawnworker processes).query_caseson theSqliteRecorderfile of the run: best feasible design, convergence history, active constraints, sensitivity ranking.export_n2writes a standalone N2 diagram without opening a browser.
Design notes
stdout isolation. Under stdio, stdout is the JSON-RPC channel. Every OpenMDAO call runs inside
diagnostics.isolated_stdout(), which diverts Python-level output to a buffer (returned ascaptured_output) under one process-wide lock. External codes write to log files in their run directory, and multi-start workers redirect their descriptors toworkers.log.Responsive event loop. Every tool that touches OpenMDAO is
asyncand runs in a worker thread (anyio.to_thread.run_sync), so a long optimization never blocks other requests.Persistence. Each problem lives in
<workdir>/<problem_id>/with itsproblem_spec.json(UTF-8, LF). A restarted server, or a spawn worker, rebuilds the problem from that file. Every driver run writes its own recording underrecordings/.No
pydoe. OpenMDAO's LHS and full-factorial generators andSimpleGADriverneedpydoe, which this package does not install;configure_optimizationwithsimple_gareturns a structured error that points to COBYLA or Nelder-Mead.OpenMDAO 3.45.2 quirks handled.
DOEDriverrecords every case as successful; a small subclass restores the per-case failure flag. Derivatives recorded byScipyOptimizeDriverbelong to the previous iterate, sosensitivity_rankingevaluates them at the recorded point instead.
Deployment on Rocky Linux 9.8
sudo deploy/rocky9_setup.sh --enableThe script installs python3.12 from AppStream, creates an unprivileged
openmdao account, builds /opt/openmdao-mcp/.venv, installs this checkout,
checks openmdao-mcp --help and a headless import, and installs
deploy/openmdao-mcp.service, which runs
--transport streamable-http --host 127.0.0.1 --port 8765 with
MPLBACKEND=Agg. Run deploy/rocky9_setup.sh --help for the options.
Layout
Module | Role |
| FastMCP factory, the 21 tool registrations, CLI |
| Thread-safe problem registry with on-disk |
| Builds components and nested groups from specs; external-command policy |
| Nonlinear/linear solvers and line searches |
| Problem definition, drivers, DOE sampling, run tools, multi-start |
| stdout isolation, approx/compute/check totals, case queries, N2 |
| Pydantic v2 models for every spec, request and response |
| Structured error envelope |
Quality checks
python -m ruff check .
python -m ruff format --check .
python -m mypy --strict src
python -m pytesttests/test_rotorcraft_mdao_benchmark.py is the end-to-end acceptance test:
a gross-weight / required-power / mission-fuel loop around a noisy black-box
CLI, checked through the step sweep, normalized multi-start SLSQP, active
constraint identification and N2 export.
Contributing
Contribution guidelines live in CONTRIBUTING.md.
License
MIT. See LICENSE.
Available Tools
21 toolscheck_totals_sweepCheck totals sweepARead-only
Finite-difference total derivatives at several step sizes, flagging derivatives that change with the step (numerical noise from black-box codes) and recommending a step. Run it before SLSQP.
Inputs: of (required), wrt (required), problem_id (required), form, +3 more. Returns: Step-size sensitivity of the total derivatives.
close_problemClose problemADestructive
Release a problem from memory; with delete_files, also delete its directory and recordings.
Inputs: problem_id (required), delete_files. Returns: Result of closing a problem.
compute_totalsCompute totalsB
Total derivatives of 'of' with respect to 'wrt' at the current point (runs the model first).
Inputs: of (required), wrt (required), problem_id (required), return_format. Returns: Total derivatives, by (of, wrt) pair or as a dense block matrix.
configure_approx_totalsConfigure approx totalsAIdempotent
Approximate the model's total derivatives by finite differences (forward/central/backward, step, step_calc) or complex step; pass spec=null to remove the approximation.
Inputs: problem_id (required), spec. Returns: What a problem looks like after it has been built.
configure_optimizationConfigure optimizationAIdempotent
Set the driver (scipy SLSQP/L-BFGS-B/trust-constr/COBYLA/Nelder-Mead, doe, analysis) and, when given, the design variables, objective and constraints. Gradient-based optimizers need ref/ref0 or scaler on every design variable.
Inputs: driver (required), problem_id (required), objective, constraints, +1 more. Returns: What a problem looks like after it has been built.
configure_solversConfigure solversAIdempotent
Set the nonlinear and linear solvers of one group (dotted path, empty for the root), e.g. NonlinearBlockGS or Newton with DirectSolver for a coupled loop. Both slots are overwritten.
Inputs: problem_id (required), group, linear_solver, nonlinear_solver. Returns: What a problem looks like after it has been built.
create_problemCreate problemB
Build an OpenMDAO problem from a declarative ProblemSpec (components, nested groups, solvers, design variables, objective, constraints, driver) and persist it as problem_spec.json.
Inputs: spec (required), run_setup, problem_id. Returns: What a problem looks like after it has been built.
export_n2Export N2BIdempotent
Write a standalone N2 diagram (HTML) into the problem directory without opening a browser.
Inputs: problem_id (required), title, outfile. Returns: Location of a generated N2 diagram.
get_outputsGet outputsBRead-only
Read current values of variables, optionally converted to given units.
Inputs: names (required), problem_id (required), units, allow_missing. Returns: Requested variable values.
get_problem_specGet problem specBRead-only
Return the stored ProblemSpec of a problem.
Inputs: problem_id (required). Returns: The stored specification of a problem.
list_problemsList problemsARead-only
List problems that are live in memory or persisted on disk.
Inputs: no named parameters. Returns: Problems known to the server, in memory or on disk.
list_variablesList variablesCRead-only
List model inputs and/or outputs with units, shape, description and current value.
Inputs: problem_id (required), kind, name_filter, max_variables, +1 more. Returns: Variable metadata entries.
load_problemLoad problemAIdempotent
Rebuild a persisted problem from its problem_spec.json (for example after a server restart).
Inputs: problem_id (required). Returns: What a problem looks like after it has been built.
pingPingBRead-only
Health check for the OpenMDAO MCP server.
Inputs: message. Returns: Response payload for the ``ping`` tool.
query_casesQuery casesBRead-only
Query a case recording with CaseReader: list, history, best_feasible, active_constraints, or sensitivity_ranking. Defaults to the problem's latest recording.
Inputs: query (required), problem_id (required), max_cases, active_tol, +2 more. Returns: Result of a case-recorder query.
run_doeRun DOEB
Design of experiments over the design variables: Latin hypercube (scipy.stats.qmc), full factorial, uniform, or an explicit list, run through DOEDriver. Failed points are reported, not fatal.
Inputs: generator (required), problem_id (required), responses, feasibility_tol, +1 more. Returns: Result of a design-of-experiments run.
run_driverRun driverB
Run the configured driver from the current point. Each run records to its own SqliteRecorder file (see query_cases). Failures are reported with success=false.
Inputs: problem_id (required), outputs, case_prefix. Returns: Result of an optimization run.
run_modelRun modelA
Evaluate the model once, optionally after setting inputs. A failed evaluation (AnalysisError) returns success=false instead of an error; converged reports nonlinear-solver convergence.
Inputs: problem_id (required), inputs, outputs. Returns: Result of a single model evaluation.
run_multistartRun multi-startB
Multi-start optimization: LHS sampling, keep the top_k feasible seeds, then a normalized local optimization (SLSQP by default) from each, in spawn worker processes when n_workers > 1.
Inputs: top_k (required), n_samples (required), problem_id (required), seed, +4 more. Returns: Result of the sample-filter-optimize multi-start pipeline.
set_inputsSet inputsBIdempotent
Set input values, optionally in given units. Values set here are not persisted to the spec.
Inputs: values (required), problem_id (required), units, allow_missing. Returns: Result of setting input values.
update_problemUpdate problemBDestructiveIdempotent
Replace a problem's spec and rebuild it. The old problem is kept if the new spec fails to build.
Inputs: spec (required), problem_id (required). Returns: What a problem looks like after it has been built.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools map to distinct lifecycle stages, and the descriptions clearly separate problem creation, update, loading, and execution. There is minor conceptual overlap between related execution tools such as run_driver, run_doe, and run_multistart, and between list_variables and get_outputs, but their intended uses are still recoverable.
Tool names consistently use lowercase snake_case with an action verb first: get_, create_, update_, load_, list_, configure_, run_, compute_, check_, query_, and export_. The lone single-verb tool, ping, is a standard health-check name and does not meaningfully break the pattern.
At 21 tools the surface is somewhat heavy, but the OpenMDAO workflow legitimately spans problem management, configuration, execution, derivative analysis, case querying, and visualization. Each tool appears to correspond to a meaningful operation rather than duplicating another, though the specialized run and check tools push the count above the typical range.
The tool set covers the full lifecycle: create/update/load/list/close problems, retrieve specs, inspect variables, set inputs, configure solvers/optimization/approximations, run models/drivers/DOE/multistart, compute and verify totals, query recordings, export N2 diagrams, and health-check the server. Deletion is handled through close_problem with delete_files, so there are no obvious dead ends.
Maintenance
Related MCP Connectors
SysML v2 systems engineering: generate, verify, simulate and export system models from text.
Manage SysML2 projects; check, evaluate, verify, query, document and diagram models.
Create and evaluate versioned decision models with reproducible results and declared assumptions.
Design domain models and generate deterministic multi-stack code, driven by your coding agent.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables automated geometry editing and aerodynamic analysis using OpenVSP and VSPAero through natural language. Provides tools to modify aircraft geometry parameters and run computational fluid dynamics simulations programmatically.38MIT
- AlicenseNot gradedqualityBmaintenanceMCP-compatible interface for discovering, loading, solving, validating, and inspecting JCGE computable general equilibrium models.Apache 2.0
- AlicenseAqualityBmaintenanceEnables running reproducible AVL 3.52 aerodynamic analyses through MCP, with input validation, isolated execution, sweeps, background jobs, and structured results including solver files.14GPL 2.0
- AlicenseCqualityBmaintenanceEnables natural-language automation of LS-PrePost preprocessing and postprocessing by exposing tools that build and verify shell meshes, query nodes, parts and connectivity, run native commands, SCL and in-application Python, and read d3plot/binout results through pluggable backends. Every job runs in its own directory and returns an ID, status, log and artifacts, so results stay traceable and failures are never silently reported as success.30MIT