openvsp-mcp - Parametric geometry for MCP workflows

TL;DR: Automate OpenVSP geometry edits and VSPAero runs so agents can generate meshes, scripts, and aerodynamic coefficients without manual GUI steps.

What it provides

Scenario	Value
OpenVSP scripting	Automate OpenVSP commands (set parameters, duplicate geometries, export meshes) without opening the GUI.
VSPAero batch runs	Launch VSPAero cases and capture generated metrics/CSV files for downstream optimisation.
MCP transport	Publish the same functionality over STDIO or HTTP via the Model Context Protocol so ToolHive or other clients can drive geometry studies remotely.

Quickstart

1. Install the package

uv pip install "git+https://github.com/Three-Little-Birds/openvsp-mcp.git"

Install the official binaries from the OpenVSP download page (this wrapper was tested with OpenVSP/VSPAero 3.46.0 on macOS). Verify they are in your PATH:

export OPENVSP_BIN=/Applications/OpenVSP/vsp export VSPAERO_BIN=/Applications/OpenVSP/vspaero

Tip (macOS/Linux): if you prefer to avoid GUI installers, build the repo's ToolHive image and run the examples inside Docker:
docker build -t openvsp-mcp-toolhive -f infra/docker/openvsp_toolhive/Dockerfile . docker run --rm --entrypoint /usr/local/bin/vsp openvsp-mcp-toolhive --version
Mount your geometry directory and set OPENVSP_BIN=/usr/local/bin/vsp when executing the Python snippets in-container.

2. Run a scripted geometry edit

from importlib import resources import shutil import tempfile from pathlib import Path from openvsp_mcp import OpenVSPRequest, VSPCommand, execute_openvsp with resources.as_file(resources.files("openvsp_mcp.data") / "rect_wing.vsp3") as bundled: with tempfile.TemporaryDirectory(prefix="openvsp_mcp_") as tmpdir: geometry_path = Path(tmpdir) / "rect_wing.vsp3" shutil.copy(bundled, geometry_path) request = OpenVSPRequest( geometry_file=str(geometry_path), set_commands=[ VSPCommand(command='string geom_id = FindGeom("RectWing", 0)'), VSPCommand(command='string span_id = GetParm( geom_id, "TotalSpan", "WingGeom" )'), VSPCommand(command='SetParmVal( span_id, 12.0 )'), VSPCommand(command='Update()'), ], run_vspaero=False, case_name="rectwing_span12", ) response = execute_openvsp(request) print("Script used:", response.script_path) print("ADB path:", response.result_path) # None unless run_vspaero=True

OpenVSPResponse contains:

script_path – absolute path to the generated .vspscript you can archive for repeatability.
result_path – VSPAero .adb file (string) when run_vspaero=True, otherwise None. Meshes, CSVs, and other artefacts are emitted by OpenVSP next to your original .vsp3.

Need a starter geometry? The package ships with openvsp_mcp.data/rect_wing.vsp3, generated from a single OpenVSP wing primitive. The snippet above uses OpenVSP script helpers (FindGeom + GetParm) so it works out of the box. For your own models, open the geometry in the GUI, note the component name returned by FindGeom, and update the commands accordingly.

Run as a service

CLI (STDIO / Streamable HTTP)

uvx openvsp-mcp # runs the MCP over stdio # or python -m openvsp_mcp python -m openvsp_mcp --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

Registered tools:

openvsp.inspect – describe a geometry without modifying it.
openvsp.modify – apply scripted parameter edits (no VSPAero).
openvsp.run_vspaero – run edits followed by VSPAero.

Use python -m openvsp_mcp --describe to list the tools at runtime.

FastAPI (REST)

uv run uvicorn openvsp_mcp.fastapi_app:create_app --factory --port 8002

Endpoints:

POST /vsp/inspect → OpenVSPInspectResponse
POST /vsp/modify → run edits only
POST /vsp/run → run edits + VSPAero

All operations return structured JSON; explore them via the interactive docs at http://127.0.0.1:8002/docs.

python-sdk tool (STDIO / MCP)

from mcp.server.fastmcp import FastMCP from openvsp_mcp.tool import build_tool mcp = FastMCP("openvsp-mcp", "OpenVSP automation") build_tool(mcp) if __name__ == "__main__": mcp.run()

Then launch with uv run mcp dev examples/openvsp_tool.py and connect your agent.

ToolHive smoke test

Requires exported binaries and a geometry file reachable inside the container:

export OPENVSP_BIN=/path/to/vsp export VSPAERO_BIN=/path/to/vspaero # optional export OPENVSP_GEOMETRY=/path/to/model.vsp3 uvx --with 'mcp==1.20.0' python scripts/integration/run_openvsp.py # ToolHive 2025+ defaults to Streamable HTTP; select the same transport when registering # the workload manually to avoid the legacy SSE 502 proxy issue.

Agent playbook

Geometry studies - script sweep operations (span, twist, control surface deflections) and archive each variant.
Aerodynamic coefficients - hand VSPAero results to ctrltest-mcp or custom controllers.
Mesh exports - agents can request STL/OBJ assets for CFD or manufacturing pipelines.

Stretch ideas

Pair with foam-agent-mcp-core to auto-generate mesh-ready cases.
Use deck.gl to visualise planform edits by surfacing geometry metadata in the response.
Schedule nightly configuration sweeps (span x sweep x incidence) and store the results for design-of-experiments studies.

Accessibility & upkeep

Run uv run pytest before committing; tests mock VSPAero calls so they finish quickly.
Keep OpenVSP/VSPAero versions consistent across developers to avoid geometry mismatches.

Contributing

uv pip install --system -e .[dev]
Run uv run ruff check . and uv run pytest
Submit PRs with sample scripts or geometry diffs so reviewers can validate quickly.

MIT license - see LICENSE.

OpenVSP ships under NASA’s license; VSPAero usage must comply with the terms that accompany your download. Commercial redistribution generally requires a separate agreement—check the official FAQ before packaging binaries into your MCP workloads.

OpenVSP MCP Server