This server provides aerodynamic simulation capabilities for flapping-wing aircraft analysis through MCP (Model Context Protocol) tools.
Core capabilities:
Aerodynamic force calculation: Compute thrust, lift, and torque for wing geometries by specifying wing parameters (span, chord), flapping schedules (frequency, amplitude), and flight conditions (velocity, air density) via the
pterasim.simulatemethodDual solver support: Automatically uses high-fidelity UVLM (Unsteady Vortex Lattice Method) when PteraSoftware is installed, with automatic fallback to fast analytical surrogate models if unavailable or convergence fails
Provenance tracking: Returns metadata indicating which solver was used (
analyticorpterasoftware_uvlm) and performance deltas between methods (e.g., thrust/lift differences in percentages)Parametric design sweeps: Support for varying wing geometry and flapping parameters across multiple simulations to explore design space and optimize performance
Integration with MCP workflows: Compatible with other MCP tools like
ctrltest-mcpfor control studies andopenvsp-mcpfor geometry-to-aerodynamics pipelinesStructured data outputs: Generate experiment logs (JSONL) suitable for control systems, reinforcement learning agents, regression dashboards, and machine learning training datasets
Multiple deployment options: Run as STDIO service, HTTP streamable service, FastAPI REST server, or integrated into MCP toolchains
Provides a REST API wrapper for the pterasim aerodynamics solver, enabling HTTP-based access to UVLM and surrogate aerodynamic simulations.
Supports routing solver provenance metadata and aerodynamic simulation results into Grafana dashboards for visualization and monitoring.
Click on "Install 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., "@Pterasim MCP Servercalculate lift and drag for a 0.8m wingspan at 12Hz flapping"
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.
pterasim-mcp - UVLM + surrogate aerodynamics for MCP agents
TL;DR: Expose PteraSoftware's analytical/UVLM solvers through MCP so agents can request aerodynamic coefficients with provenance metadata.
Table of contents
What it provides
Scenario | Value |
Surrogate aerodynamics | Evaluate lightweight rigid-vortex-lattice models without a GUI, returning aerodynamic coefficients as structured data. |
High-fidelity UVLM | When PteraSoftware is installed, the service switches to its UVLM solver and records provenance metadata. |
Controller integration | Provide consistent outputs that downstream MCP tools (e.g., |
Quickstart
1. Install
uv pip install "git+https://github.com/Three-Little-Birds/pterasim-mcp.git"2. Run an analytic solve
from pterasim_mcp import PterasimInput, simulate_pterasim
request = PterasimInput(
span_m=0.8,
mean_chord_m=0.12,
stroke_frequency_hz=12.0,
stroke_amplitude_rad=0.55,
cruise_velocity_m_s=6.0,
air_density_kg_m3=1.225,
cl_alpha_per_rad=6.2,
cd0=0.03,
planform_area_m2=0.18,
)
response = simulate_pterasim(request)
print(response.metadata["solver"]) # "analytic" or "pterasoftware_uvlm"
print(response.thrust_N, response.lift_N, response.torque_Nm)
Typical metadata payload:
```json
{
"solver": "pterasoftware_uvlm",
"thrust_delta_pct_vs_analytic": -4.1,
"lift_delta_pct_vs_analytic": -2.7
}
If a Python 3.13 environment with `PteraSoftware` (≥3.2) is available, the wrapper will prefer UVLM and note the solver in the metadata. Install it inside a dedicated environment:
```bash
uv python install 3.13
uv venv .venv-pterasim --python 3.13
source .venv-pterasim/bin/activate
pip install pterasoftware==3.2.0
uv pip install "git+https://github.com/Three-Little-Birds/pterasim-mcp.git"If the UVLM solve fails for any reason (missing binaries, convergence issues, or the current PteraSoftware regression that removes geometry.airfoil), the wrapper logs a warning and falls back to the analytic surrogate—you will see solver: "analytic" in the metadata and no delta fields. UVLM runs with thousands of timesteps can take minutes; batch analytic sweeps first and promote only promising cases to the high-fidelity environment. Analytic-only mode works on Python 3.11 without PteraSoftware. Until the UVLM API stabilizes upstream, treat the analytic path as the supported/default mode.
Run as a service
CLI (STDIO / Streamable HTTP)
uvx pterasim-mcp # runs the MCP over stdio
# or python -m pterasim_mcp
python -m pterasim_mcp --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcpUse python -m pterasim_mcp --describe to emit metadata without starting the server.
FastAPI (REST)
uv run uvicorn pterasim_mcp.fastapi_app:create_app --factory --port 8003python-sdk tool (STDIO / MCP)
from mcp.server.fastmcp import FastMCP
from pterasim_mcp.tool import build_tool
mcp = FastMCP("pterasim-mcp", "Wing UVLM & surrogate solver")
build_tool(mcp)
if __name__ == "__main__":
mcp.run()ToolHive smoke test
uvx --with 'mcp==1.20.0' python scripts/integration/run_pterasim.py
# ToolHive 2025+ defaults to Streamable HTTP; match that transport when registering
# the workload manually so IDE clients avoid the SSE 502 bug.Agent playbook
Scenario sweeps - vary span, frequency, or flapping amplitude and log derivatives for control studies.
Solver comparison - leverage metadata to benchmark surrogate vs UVLM deltas and store the comparisons for regression dashboards.
Design flows - combine with
openvsp-mcpto generate geometry + aerodynamics pipelines.
Stretch ideas
Generate JSONL experiment logs that feed directly into
ctrltest-mcpor reinforcement-learning agents.Use the metadata to route results into Grafana dashboards for solver provenance.
Auto-promote surrogate runs to UVLM once a high-fidelity environment is detected.
Accessibility & upkeep
Tests simulate solver responses; run
uv run pytestbefore pushing.Keep
.venv-pterasimaligned with the PteraSoftware version you report in metadata.
Contributing
uv pip install --system -e .[dev]Run
uv run ruff check .anduv run pytestInclude sample metadata/CSV artefacts in PRs so reviewers can confirm provenance handling.
MIT license - see LICENSE.