avl-mcp
This server wraps AVL 3.52 to inspect/validate models and run reproducible aerodynamic analyses, trims, sweeps, and durable background jobs, then page saved results.
Diagnose AVL/Python installation, architecture, directory permissions, and headless startup with
avl.health.Read geometry, references, controls, and dependencies with
avl.inspectwithout changing original files.Validate supported AVL text grammar, dependency paths, and mesh limits without running the solver.
Run one prescribed flight condition and return forces, ST/SB derivatives, surface loads, and strip outputs.
Solve aerodynamic lift/pitch trim by varying alpha plus one CONTROL, with bounds and independent verification.
Run 1–10,000 prescribed conditions or trim targets in sweeps, grouped by Mach, with saved CSV/summary results.
Submit detached background jobs that survive client disconnection; monitor, cancel, resume, and page results via
avl.status,avl.cancel,avl.resume, andavl.results.Query saved results by job ID, case index, and dotted field names without rerunning AVL.
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., "@avl-mcp Run AVL analysis on wing.avl at alpha 5, Mach 0.3"
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.
avl-mcp
Run reproducible AVL aerodynamic analyses through the Model Context Protocol. The server validates input, runs AVL in an isolated directory, and returns structured results with the original solver files.
Version: 0.5.0. Supports AVL 3.52 only. Native acceptance covers macOS Apple Silicon and Ubuntu 24.04 x86_64; other platforms are unverified. This project is an independent wrapper, not an official MIT or AVL release.
繁體中文說明 · Documentation index · Validation
Version 0.5.0 adds synchronous and durable background trim batches, retaining each point's acceptance bounds, residual checks and independent replay. It also adds a reproducible Linux native build and acceptance job alongside macOS. It also adds general mesh sensitivity and mass/weight, speed and CG trim inputs, with explicit unit conversion and saved provenance. See batch trim, Ubuntu installation, trim conventions and acceptance. See the 0.5.0 release notes for artifacts and upgrade scope. Installing a release does not update an existing client's configuration automatically.
Tools
Tool | Purpose |
| Diagnose Python/native installation, directory access and headless startup |
| Read geometry, references, controls and file dependencies |
| Check supported grammar, dependency paths and mesh budget |
| Calculate one prescribed condition, loads and ST/SB derivatives |
| Solve alpha and one CONTROL variable for target CL/Cm, then independently verify |
| Compare coefficients across refined surface meshes and save JSON/CSV/Markdown |
| Convert explicit mass/weight, airspeed and CG to CL targets and references without running AVL |
| Run independently verified trim from dimensional inputs and retain conversion provenance |
| Calculate 1-10000 prescribed conditions or independently verified trim targets and save CSV |
| Snapshot prescribed conditions or trim targets and start a detached background job |
| Read progress, counts and the actual job outcome |
| Cancel a queued/running job while retaining completed cases |
| Verify saved inputs/results and recompute only missing or failed cases |
| Page and filter saved results without running AVL |
The connector does not expose eigenmodes, general geometry editing, interactive graphics, CAD conversion, or automatic OpenVSP comparison. The model validator checks input structure and basic invariants; it does not prove freedom from intersections or aerodynamic suitability. A successful process exit alone is never accepted as a result.
Related MCP server: tigl-mcp
Installation
Requirements: Python 3.11 or newer and a separately installed AVL 3.52 executable. The Python package does not download or bundle AVL, install system libraries, or modify any MCP client configuration.
python3 -m venv /absolute/local/path/avl-mcp-env
/absolute/local/path/avl-mcp-env/bin/python -m pip install .
/absolute/local/path/avl-mcp-env/bin/avl-mcp --versionFor development, install .[dev] in a local environment. Build release artifacts
with python -m build; install the resulting wheel for the stdio acceptance test.
Keep virtual environments and native libraries on each machine's local disk.
Research inputs, results and logs can be stored in a separate project directory.
A compatible prebuilt AVL 3.52 executable can also be used; compiling AVL is not an inherent MCP requirement. See native installation. Python release artifacts are a wheel, source distribution and checksums; AVL remains a separate installation. The existing optional native bundle is retained on the v0.1.0a1 release.
For Ubuntu 24.04 x86_64, use the Linux build and validation guide. It builds verified upstream source with GNU compilers, X11 and the numerical libraries shipped in the AVL archive. Headless analysis does not require an X server.
Building AVL on macOS Apple Silicon
The upstream 3.52 source archive is available at
https://web.mit.edu/drela/Public/web/avl/avl3.52.tgz.
The archive used for this release has SHA-256
0b588ecea9222f5b625d0af0c87ae31daf3cdba1532cf0bbb36f93d6e854849b.
Upstream requires Fortran/C compilers, a plotting library and numerical libraries.
This project includes a helper for a task-local conda-forge environment containing
gfortran_osx-arm64=14, xorg-libx11, and xorg-xorgproto. The last package
provides the X11 protocol headers needed at build time. Xcode Command Line Tools
must already be available. A platform-specific dependency lock records the tested
compiler environment in docs/native-dependencies-osx-arm64.lock.
python scripts/build_avl_macos.py \
--source /absolute/path/to/extracted/AVL3.52rel09032025 \
--compiler-prefix /absolute/local/path/to/compiler-environment \
--logs /absolute/path/to/project/logsThe helper modifies only the disposable build copy's plot-library configuration,
and overrides compiler/linker flags. It does not patch the numerical solver.
scripts/bundle_avl_macos.py can collect the required dylibs into a new local
directory and update their relative load paths. The current execution path disables
graphics, so a running X server is not required. X11 libraries remain link dependencies.
Interactive plotting is not tested or exposed by this MCP.
MCP client configuration
Example Codex configuration, using absolute paths chosen for your machine:
[mcp_servers.avl]
command = "/absolute/local/path/avl-mcp-env/bin/avl-mcp"
args = [
"--avl-bin", "/absolute/local/path/avl-3.52/bin/avl",
"--work-root", "/absolute/path/to/project/AVL",
"--input-root", "/absolute/path/to/approved/model-directory"
]
tool_timeout_sec = 660--input-root is optional. If supplied, model files must resolve inside that root.
Dependencies must remain inside the model's own directory, even without this option.
For synchronous calls, set the client timeout above the requested analysis time budget.
For long analyses, use avl.submit; its short response does not wait for the solver.
Equivalent environment variables are AVL_BIN, AVL_MCP_WORK_ROOT, and
AVL_MCP_INPUT_ROOT. The default budget is 5,000 estimated vortices per case;
--max-vortices can explicitly raise it up to 20,000. This is an estimate, not a RAM guarantee.
Installing a wheel and testing a standalone MCP process do not register tools in an already running desktop session. Client registration/reload is a separate step.
For connection troubleshooting, run avl-mcp --diagnose or avl-mcp --check-mcp
with the same AVL/work-root arguments. They print structured evidence without
changing client settings. Diagnostic layers and workflow
distinguish native startup, numerical tests, fresh stdio and desktop registration.
Example requests
Inspect an official example:
{"model_path": "/absolute/path/to/avl-mcp/examples/official/vanilla/vanilla.avl"}Run a prescribed condition with avl.run:
{
"model_path": "/absolute/path/to/vanilla.avl",
"condition": {
"alpha_deg": 3.0,
"beta_deg": 0.0,
"mach": 0.2,
"pb_2v": 0.0,
"qc_2v": 0.0,
"rb_2v": 0.0,
"controls": {"elevator": 1.0}
},
"case_name": "vanilla-elevator",
"timeout_seconds": 120,
"length_unit": "unspecified"
}controls maps the CONTROL variable names in the geometry to their values.
Local deflection in degrees equals the variable value multiplied by that section's
gain; it is not necessarily the physical deflection of every connected surface.
Unknown control names are rejected. Omitted controls and angular rates are zero.
Omitted Mach uses the geometry header. Nearby .run and .mass files are
intentionally not loaded in prescribed-condition analyses.
Longitudinal aerodynamic trim
Call avl.trim to solve alpha and one named CONTROL variable at a required Mach:
{
"model_path": "/absolute/path/to/vanilla.avl",
"request": {
"control": "elevator",
"target_cl": 0.6,
"target_cm": 0.0,
"mach": 0.2,
"alpha_bounds_deg": [-10.0, 15.0],
"control_bounds": [-30.0, 30.0],
"fixed_controls": {"flap": 0.0},
"cl_tolerance": 0.000001,
"cm_tolerance": 0.000001
},
"case_name": "vanilla-trim",
"timeout_seconds": 120,
"outputs": ["total"]
}Beta and all angular rates are zero. Other controls are fixed at the requested
values, defaulting to zero. CONTROL values retain the geometry's gains and signs;
they are not automatically physical elevator deflections. Cm refers to the model's
moment reference, or an explicit references override, which is not necessarily
the aircraft CG. No .mass or .run file is loaded.
AVL's native solver is unconstrained: the required bounds decide whether its
solution is acceptable and do not clip the result or constrain its iterations.
A successful result must meet CL/Cm residual tolerances and bounds, then pass
a fresh fixed-condition run at the solved alpha and control values. The saved
trim metadata separates the request, solved condition, residuals, bounds and
verification. This is aerodynamic lift/pitch-moment trim, without weight/thrust
balance. See the full trim contract and failure behavior.
Use avl.sweep with model_path and exactly one of conditions or trim_requests.
For prescribed conditions, its execution budget is
300 seconds by default (one total budget, not a separate allowance per condition).
Cases are grouped by Mach to reuse AVL's matrix factorization and returned in the
original request order. Each native process handles at most 128 conditions; the
connector explicitly resets every angular rate and control at every point.
Execution stops on the first error unless stop_on_error=false; remaining cases
then use a fresh process. Timeout/cancellation always stops the attempt.
The MCP response includes at most 25 case summaries; use avl.results to page the rest.
Completed cases and failed-attempt logs remain available. A partial synchronous
sweep returns isError=true. Full results are in result.json.
For trim batches, pass trim_requests: [<TrimRequest>, ...] instead of conditions.
Each request has the same required targets, control and bounds as avl.trim above.
Every point runs a fresh native trim followed by independent prescribed-condition
verification; all points and replays share the total timeout budget. The same
input works with avl.submit for cancellation, verified resume and progress.
See batch examples, saved results and failure semantics.
Select outputs
avl.run, avl.trim, avl.trim_physical, avl.sweep and avl.submit accept outputs.
Omit it to retain the
previous complete output set. Use ["total"] for forces/moments only, or e.g.
["total", "body"] to add body-axis derivatives. Supported tables are total,
stability, body, surfaces, strips. Total output is always retained to verify
that AVL used the requested conditions. Skipped tables are not generated or
parsed; querying one later reports FIELD_NOT_AVAILABLE rather than rerunning AVL.
Durable background jobs
Call avl.submit with the same model, conditions or trim_requests, and outputs as a sweep.
It returns a job_id; use that ID with avl.status, avl.cancel, avl.resume
and avl.results. Workers run independently of the MCP connection and keep their
state under <work-root>/jobs/. At most two background jobs execute at once per
work root; additional workers wait. Synchronous calls are outside this queue.
avl.status returns queued, running, completed, failed, cancelled or
interrupted, completed/failed counts, and the last error. success=true means
the status query succeeded, not that the solver job passed. Cancellation is
cooperative: query until acknowledged. Only that worker's owned AVL process is
stopped. Completed cases and all native attempts are retained.
An inactive job can be resumed from another MCP connection using the same work root and implementation. Resume checks original geometry and dependencies, staged input hashes, settings, executable hash, and the MCP implementation hash. Changed inputs/solver/code require a new job. Valid successful case checkpoints are reused; missing/damaged outputs and failed cases are recomputed. Timeouts apply per execution attempt (excluding queue time); resume grants the same budget again. A worker lost during startup may take up to 30 seconds to be identified. Do not edit/remove active job files. Cross-machine/network-filesystem locking is not established; use one host per work root.
Query coefficients without invoking a solver:
{
"job_id": "<id returned by submit, run, trim or sweep>",
"indices": [0, 3, 8],
"fields": ["total.fields.CLtot", "body.derivatives.Cmq"],
"offset": 0,
"limit": 20
}avl.results pages cases in original index order (limit 1-100); indices filters
that list. Dotted field names preserve case, e.g. stability.control_derivatives.elevator.Cm.
With no fields, each row includes total coefficients and saved artifact paths,
including strip CSV/JSON when requested. Unfinished cases are absent, not zeros.
Large responses are rejected with a request to narrow the selection. Results can
be read even when the AVL executable is unavailable. For older runs, the directory
basename is the run ID. Job control tools apply only to background jobs.
Optional references must specify all six values: sref, cref, bref, xref,
yref, zref. Overrides affect only the staged copy. Cref, Bref, and the three
coordinates use the geometry's length unit; Sref uses its square. length_unit
labels the data (m, ft, in, or unspecified); it does not convert geometry.
For the official Bubble Dancer example, the supplied mass file documents inches.
Results and conventions
Every successful case adds a versioned result_contract, also saved as
result-contract.json: actual reference dimensions/point, units, axes, coefficient
normalizations, ST/SB derivative variables and section control gains. Compact
result_context accompanies sweep summaries and selected saved-result queries.
Unknown units stay Lunit; native coefficients are unchanged. Separately calculated
derived.wind_forces records the rotation of native stability totals.
See the complete result contract, including two upstream 3.52 caveats exposed by tests: constant CDp with sideslip can make native stability and body force projections differ, and ST alpha derivatives at nonzero p/r can differ from fixed-stability-rate perturbations. Applicable cases carry explicit limitation codes and warnings; no native number is silently corrected.
Synchronous executions use <work-root>/runs/; background jobs use <work-root>/jobs/.
Each job retains native process folders and separate per-case outputs:
Original input snapshots, staged geometry and dependencies, and SHA-256 records.
manifest.json, exactcommands.txt,stdout.log,stderr.log,process.json.Raw
total.mrfand the other selected MRF tables.Parsed
result.json; selected strips addstrips.json/strips.csv, synchronous sweeps addsummary.csv.Background input snapshots, atomic per-case checkpoints, attempt records and worker logs.
The parser requires MRF VERSION 1.0, complete tables and finite numerical values.
It verifies all 30 ST or 36 SB derivatives, every declared CONTROL/DESIGN column,
integer counts, unique fields, load indices and matching load references. Missing
rows, duplicate records and truncated DESIGN tails fail instead of returning partial success.
It distinguishes missing/truncated output, solver diagnostics, version mismatch,
timeouts, changed input, and requested-versus-actual condition mismatch.
Logs go to files, never to the MCP protocol's stdout channel.
Quantity | Convention |
Geometry coordinates | X aft, Y right, Z up |
Input angular rates | Standard body axes: X forward, Y right, Z down; pb/(2V), qc/(2V), rb/(2V) |
| Standard body-axis force/moment coefficients |
| Stability-axis lift/drag; stability-axis roll/yaw moments |
| Stability-axis derivatives; alpha/beta derivatives per radian |
| Body-axis derivatives; normalized velocity and angular-rate variables |
Control derivatives | Per CONTROL variable unit, including geometry gains |
Moment reference | Xref/Yref/Zref; not necessarily a mass-derived aircraft CG |
| Near-field induced contribution |
| Trefftz-plane induced drag; keep separate from CDind |
| Supplied profile-drag model; not a viscous flow solution |
Raw key case is preserved: CL is lift and Cl is roll moment. At nonzero
beta, stability axes and full wind axes differ. Undefined AVL diagnostic sentinels
for neutral point/spiral parameter are returned as JSON null, not physical values.
Limits and validation
AVL is a thin lifting-surface, slender-body and quasi-steady potential-flow model. It does not establish stall, separated-flow or transonic accuracy. The connector accepts 0 <= Mach < 0.7 and warns on large angles/high Mach; those limits do not certify physical accuracy. Numerical agreement between wrappers or solvers is not flight validation.
See docs/validation.md for the tested conditions and scope. The included geometries come from the official AVL archive. Regression snapshots are generated outputs on the tested build, not published experimental truth.
AVL_BIN=/absolute/path/to/avl python -m pytest -q
python scripts/verify_stdio.py \
--command /absolute/path/to/avl-mcp-env/bin/avl-mcp \
--avl-bin /absolute/path/to/avl \
--work-root /absolute/path/to/project/AVL \
--vanilla examples/official/vanilla/vanilla.avl \
--bd examples/official/bd/bd.avlNative tests are explicitly skipped if AVL_BIN is absent. Use
AVL_TEST_WORK_ROOT to retain native pytest run artifacts in a chosen directory.
Roadmap
Add explicit control mixing and mass/inertia-dependent flight trim or eigenmode analysis after their input and verification contracts are defined.
Add controlled geometry generation and previews after the analysis interface stabilizes.
Research aircraft models and CFD data are not part of this repository.
License and acknowledgements
This repository is released under GPL-2.0-or-later; see LICENSE. AVL is by Mark Drela and Harold Youngren. The official source and MRF readers carry GPL-2.0-or-later notices, with additional contributor credits in their source files. Example inputs retain their upstream content; see THIRD_PARTY_NOTICES.md. The numerical solver is installed separately. Distributing native binaries requires preserving their applicable notices, licenses and corresponding-source obligations, including those of bundled libraries. No native binary is included in the Python wheel.
Available Tools
14 toolsavl.cancelAIdempotent
Request cooperative cancellation of this job's worker and its owned AVL process. Completed cases and logs remain. Query status until cancellation is acknowledged.
Inputs: job_id (required).
avl.healthA
Diagnose Python/native dependencies, architecture, directory permissions and AVL startup. Save evidence. Numerical validation and desktop registry refresh remain separate.
Inputs: no named parameters.
avl.inspectARead-onlyIdempotent
Read geometry, references, controls and dependencies; original files are unchanged.
Inputs: model_path (required).
avl.mesh_sensitivityA
Compare a fixed flight condition across 2-8 increasing mesh factors starting at 1. Refine surface chord/span counts on staged copies; body discretization stays fixed. Preflight every mesh against the configured vortex budget. Save coefficients, baseline/adjacent differences, JSON, CSV and Markdown with one total timeout. Optional absolute tolerances only assess the final adjacent difference; no automatic mesh-convergence claim, Richardson extrapolation, or geometry suitability proof.
Inputs: request (required), model_path (required), case_name, references, +2 more.
avl.prepare_trimARead-onlyIdempotent
Convert explicit SI mass/weight, density and speed to target CL without running AVL. Require geometry length units and a CG with units; set the moment reference to CG. Return a TrimRequest and References usable in trim/sweep/submit, plus provenance. Assumes unbanked steady level lift=weight, zero beta/rates and target Cm=0. Mach is supplied separately; no inferred atmosphere, thrust balance or inertia model.
Inputs: request (required), model_path (required), references.
avl.resultsARead-onlyIdempotent
Page saved background or run/sweep results without running AVL. Limit 1-100 cases. Filter by original zero-based indices and dotted fields, e.g. total.fields.CLtot, body.derivatives.Cmq, stability.control_derivatives.elevator.Cm. Missing tables return FIELD_NOT_AVAILABLE; raw/strip artifact paths remain available by default.
Inputs: job_id (required), limit, fields, offset, +1 more.
avl.resumeA
Resume an inactive job after verifying input, solver, implementation and output hashes. Recompute only failed, missing or damaged cases. Active jobs cannot be resumed.
Inputs: job_id (required).
avl.runA
Run one prescribed flight condition. Return forces, ST/SB derivatives, surface loads and links to strip CSV/JSON. Angles in degrees, rates nondimensional BODY axes; CONTROL values use gains defined in geometry. Default controls/rates zero. A references override changes only the staged copy. Ignores nearby .run/.mass.
Inputs: model_path (required), outputs, case_name, condition, +3 more.
avl.statusBRead-onlyIdempotent
Read queued/running/completed/failed/cancelled/interrupted state and case counts. success=true means the status was read; inspect state/error for solver outcome.
Inputs: job_id (required).
avl.submitA
Snapshot inputs and start a detached local AVL job; return job_id immediately. 1-10000 cases, at most two background workers execute per work root. Workers survive MCP client disconnection. Timeout is the execution budget per attempt, excluding queue. Supply exactly one of conditions or trim_requests. Every trim requires its own fresh verification; cancel interrupts candidate/replay and resume reuses verified cases only. outputs=['total'] skips derivatives/surface/strip output; None requests all tables.
Inputs: model_path (required), outputs, case_name, conditions, +5 more.
avl.sweepA
Supply exactly one of conditions or trim_requests, each containing 1-10000 cases. Prescribed conditions share AVL processes grouped by Mach, resetting rates/controls. Trim requests run sequentially: each solves alpha/CONTROL for CL/Cm and independently replays in a fresh process. All cases and replays share one total timeout budget. Return cases in requested order with trim residuals, bounds and verification metadata. Select outputs (total is always retained); None preserves all previous tables. Preserve successful and failed cases and write summary.csv. For long jobs use submit. Return partial results and isError=true if any requested case is unsuccessful.
Inputs: model_path (required), outputs, case_name, conditions, +5 more.
avl.trimA
Solve alpha and one existing CONTROL for target CL/Cm at zero beta/body rates. CONTROL values retain section gains, not automatically physical deflection degrees. Bounds accept/reject the native solution, not constrain iterations. Success requires residual/bounds checks and a fresh fixed-condition solve. Moments use the explicit geometry/override reference point, not an inferred CG. No mass/thrust balance.
Inputs: request (required), model_path (required), outputs, case_name, +3 more.
avl.trim_physicalA
Prepare lift=weight and zero pitching moment about explicit CG, then verify trim. Takes SI mass/weight, density and speed plus declared geometry/CG length units. Solves alpha and one CONTROL with bounds/residual checks and independent replay. Save dimensional inputs and conversion provenance with native results, including numerical failures. Mach remains explicit. No thrust balance, mass file or eigenmodes.
Inputs: request (required), model_path (required), outputs, case_name, +2 more.
avl.validateARead-onlyIdempotent
Validate supported text grammar, dependencies and mesh limits. No solver execution.
Inputs: model_path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools have clearly distinct roles: single-case run, multi-case sweep, detached submit, and job control/status/results are readily separable. The main ambiguity is within the trim family (prepare_trim, trim, trim_physical), though their descriptions clarify whether AVL is executed and what inputs are required.
All names use lower snake_case under the avl. namespace, which is consistent at the lexical level. However, the set mixes imperative verbs (run, sweep, submit, inspect) with noun-like resource names (status, results, health) and compound descriptive forms (mesh_sensitivity, trim_physical), so it is readable but not a predictable verb_noun convention.
Fourteen tools is well within the appropriate range for a complex AVL analysis server. Each major phase—inspection, validation, execution, background job control, and result retrieval—has a dedicated tool without obvious filler.
The surface covers the core AVL lifecycle: inspect/validate/health, trim preparation, run/sweep/submit, status/cancel/resume, and results retrieval. Minor gaps such as a job-list operation or explicit geometry/setup management are not central to the apparent analysis scope, but there is no obvious dead end.
Maintenance
Related MCP Connectors
Physics-based validation of simulation results: receipts with per-check verdicts, via MCP.
Deterministic MCP, JSON Schema, and SemVer preflight via Agothe's public MUV scope.
MCP server for aerospace calculations: orbital mechanics, ephemeris, DSN operations, ...
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables aerodynamic analysis through XFOIL polar computations. Provides typed models and tools to run airfoil performance analyses from agents or automation workflows.1MIT
- AlicenseBqualityBmaintenanceProvides MCP tools for CPACS-oriented TiGL workflows, enabling lifecycle management, inspection, export, and parameter manipulation of aircraft geometry models without native geometry runtimes.113MIT
- FlicenseAqualityDmaintenanceProvides aerodynamic analysis tools through MCP, enabling geometry generation, meshing, CFD solving, and visualization for 2D airfoils.7-
- AlicenseAqualityBmaintenanceMaintained fork of Three-Little-Birds/openvsp-mcp, adding OpenVSP geometry inspection, typed parameter editing, SVG/STL previews, validated VSPAERO analysis, and durable parallel batches with progress, cancellation, resume, and CSV/JSON export. Independently maintained by rhyne1012; not an official OpenVSP or NASA project.18MIT