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.

Table of contents

1. What it provides
2. Quickstart
3. Run as a service
4. Agent playbook
5. Stretch ideas
6. Accessibility & upkeep
7. Contributing

What it provides

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

1. Pair with foam-agent-mcp-core to auto-generate mesh-ready cases.
2. Use deck.gl to visualise planform edits by surfacing geometry metadata in the response.
3. 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

1. uv pip install --system -e .[dev]
2. Run uv run ruff check . and uv run pytest
3. 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.