Skip to main content
Glama

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 pytest

Linux:

python3.12 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest

Run the end-to-end example (Sellar problem: coupled loop, scaled SLSQP, active constraints):

PYTHONPATH=src python examples/client/sellar_mdao_workflow.py

Related MCP server: JCGEAgentInterface

Running the server

Local use over stdio (the default transport):

openmdao-mcp --transport stdio

Remote use over streamable HTTP:

openmdao-mcp --transport streamable-http --host 127.0.0.1 --port 8765 --allowed-commands /opt/solvers/bin/rotor_perf

Option

Meaning

--transport {stdio,streamable-http}

Default stdio.

--host, --port, --path

HTTP only. --host defaults to 127.0.0.1.

--workdir DIR

Problem specs, recordings and external-code runs. Default $OPENMDAO_MCP_WORKDIR, else ~/.openmdao_mcp.

--allowed-commands LIST

Comma-separated executable paths or names that external_code components may run, or *. Without it, stdio allows any command and streamable-http disables external_code.

--log-level LEVEL

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

ping

Problems

create_problem, update_problem, load_problem, list_problems, get_problem_spec, close_problem

Variables

list_variables, set_inputs, get_outputs

Solvers and drivers

configure_solvers, configure_optimization

Runs

run_model, run_driver, run_doe, run_multistart

Derivatives

configure_approx_totals, compute_totals, check_totals_sweep

Observability

query_cases, export_n2

A typical session:

  1. create_problem with a ProblemSpec: independent variables, exec_comp equations (checked against an AST whitelist), external_code black boxes (template in, run in an isolated eval_<uuid> directory, JSONPath/regex out), metamodel surrogates, and nested groups with their own solvers.

  2. run_model to converge the coupled loop at the baseline.

  3. configure_optimization: design variables (gradient-based optimizers require ref/ref0 or scaler), objective, constraints, driver.

  4. check_totals_sweep before SLSQP: finite-difference totals at several steps expose black-box noise and recommend a step for configure_approx_totals.

  5. run_doe (LHS via scipy.stats.qmc, full factorial via itertools.product, both fed to ListGenerator), run_driver, or run_multistart (LHS, keep the best feasible seeds, normalized SLSQP from each, optionally in spawn worker processes).

  6. query_cases on the SqliteRecorder file of the run: best feasible design, convergence history, active constraints, sensitivity ranking.

  7. export_n2 writes 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 as captured_output) under one process-wide lock. External codes write to log files in their run directory, and multi-start workers redirect their descriptors to workers.log.

  • Responsive event loop. Every tool that touches OpenMDAO is async and 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 its problem_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 under recordings/.

  • No pydoe. OpenMDAO's LHS and full-factorial generators and SimpleGADriver need pydoe, which this package does not install; configure_optimization with simple_ga returns a structured error that points to COBYLA or Nelder-Mead.

  • OpenMDAO 3.45.2 quirks handled. DOEDriver records every case as successful; a small subclass restores the per-case failure flag. Derivatives recorded by ScipyOptimizeDriver belong to the previous iterate, so sensitivity_ranking evaluates them at the recorded point instead.

Deployment on Rocky Linux 9.8

sudo deploy/rocky9_setup.sh --enable

The 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

openmdao_mcp.server

FastMCP factory, the 21 tool registrations, CLI

openmdao_mcp.session

Thread-safe problem registry with on-disk problem_spec.json

openmdao_mcp.components

Builds components and nested groups from specs; external-command policy

openmdao_mcp.solvers

Nonlinear/linear solvers and line searches

openmdao_mcp.drivers

Problem definition, drivers, DOE sampling, run tools, multi-start

openmdao_mcp.diagnostics

stdout isolation, approx/compute/check totals, case queries, N2

openmdao_mcp.schemas

Pydantic v2 models for every spec, request and response

openmdao_mcp.errors

Structured error envelope

Quality checks

python -m ruff check .
python -m ruff format --check .
python -m mypy --strict src
python -m pytest

tests/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 tools
check_totals_sweepCheck totals sweepA
Read-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 problemA
Destructive

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 totalsA
Idempotent

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 optimizationA
Idempotent

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 solversA
Idempotent

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 N2B
Idempotent

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 outputsB
Read-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 specB
Read-only

Return the stored ProblemSpec of a problem.

Inputs: problem_id (required). Returns: The stored specification of a problem.

list_problemsList problemsA
Read-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 variablesC
Read-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 problemA
Idempotent

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.

pingPingB
Read-only

Health check for the OpenMDAO MCP server.

Inputs: message. Returns: Response payload for the ``ping`` tool.

query_casesQuery casesB
Read-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 inputsB
Idempotent

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 problemB
DestructiveIdempotent

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

    A3.5/5.0

    Scored across 21 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables running reproducible AVL 3.52 aerodynamic analyses through MCP, with input validation, isolated execution, sweeps, background jobs, and structured results including solver files.
      14
      GPL 2.0
    • A
      license
      C
      quality
      B
      maintenance
      Enables 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.
      30
      MIT