Flappy MCP Server
Provides a REST API transport layer for the Flappy simulator, exposing trajectory simulation capabilities through HTTP endpoints with auto-generated documentation.
Wraps the Purdue BioRobotics Flappy CLI simulator, enabling programmatic control of flapping-wing dynamics simulations and trajectory data collection for reinforcement learning and system identification studies.
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., "@Flappy MCP Server simulate a 10-second flight with default parameters"
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.
flappy-mcp - Bio-inspired flapping dynamics for MCP agents
TL;DR: Control the Purdue BioRobotics "Flappy" simulator through MCP so agents can explore flapping-wing dynamics and log trajectories without headless GUIs.
Table of contents
Related MCP server: OpenVSP MCP Server
What it provides
Scenario | Value |
Flappy CLI automation | Drive the Purdue BioRobotics Flappy simulator from Python or MCP without bespoke shell scripts. |
Trajectory logging | Collect pose, velocity, and energy histories as JSON for reinforcement learning or system-identification studies. |
MCP transport | Expose the CLI via STDIO/HTTP so ToolHive and other clients can batch missions or plug results into |
Quickstart
1. Install the wrapper
uv pip install "git+https://github.com/Three-Little-Birds/flappy-mcp.git"Build the CLI from the Purdue SMARTLab Flappy sources (partners receive access on request—see the research page for contact details) and point this wrapper to the resulting flappy_cli binary:
export FLAPPY_BIN=/path/to/flappy_cli2. Simulate a trajectory
from flappy_mcp import FlappyRequest, execute_flappy
request = FlappyRequest(
scenario=None,
fallback={"duration_s": 5.0, "timestep_s": 0.01},
)
response = execute_flappy(request)
print("Trajectory points:", len(response.trajectory))
print("Source:", response.source) # "generated" or path to CLI JSON
print("First sample:", response.trajectory[0].model_dump())Run as a service
CLI (STDIO transport)
uvx flappy-mcp # runs the MCP over stdio
# or python -m flappy_mcpUse python -m flappy_mcp --describe to inspect metadata without starting the server.
FastAPI (REST)
uv run uvicorn flappy_mcp.fastapi_app:create_app --factory --port 8004Invoke via the auto-generated docs at http://127.0.0.1:8004/docs.
python-sdk tool (STDIO / MCP)
from mcp.server.fastmcp import FastMCP
from flappy_mcp.tool import build_tool
mcp = FastMCP("flappy-mcp", "Flapping dynamics simulator")
build_tool(mcp)
if __name__ == "__main__":
mcp.run()Launch with uv run mcp dev examples/flappy_tool.py and wire in your agent.
ToolHive smoke test
Requires the Flappy CLI executable:
export FLAPPY_BIN=/path/to/flappy_cli
uvx --with 'mcp==1.20.0' python scripts/integration/run_flappy.pyAgent playbook
Policy tuning - sweep control inputs and feed trajectories into reinforcement-learning pipelines.
Sensor synthesis - generate inertial traces for testing perception/estimation stacks.
Energy studies - derive energy usage from the returned stroke kinematics or augment the scenario before launching the CLI.
Stretch ideas
Couple with
diffsphgradients to evaluate loads alongside motion.Feed trajectories into
ctrltest-mcpfor closed-loop evaluation.Build deck.gl overlays of position data for mission rehearsal.
Install & maintenance
Runtime install: follow the Quickstart
uv pip install "git+https://github.com/Three-Little-Birds/flappy-mcp.git"step on machines that need the MCP wrapper.Validate dependencies: set
FLAPPY_BINto the compiledflappy_clipath, run$FLAPPY_BIN --help, and confirm the simulator launches without interactive prompts.Runtime expectations: CLI runs block until completion and may take several minutes for long scenarios; the built-in sinusoidal fallback returns instantly. All trajectories are returned as lists of
{t, angle}samples in SI units so downstream controllers can replay them verbatim.Keep fixtures in sync: document any generated trajectories or fixture updates so downstream services can replay them reliably.
Contributing
uv pip install --system -e .[dev]Run
uv run ruff check .anduv run pytestSubmit sample trajectories or metrics with your PR so reviewers can validate quickly.
MIT license - see LICENSE.
Available Tools
1 toolflappy.simulateC
Run the Flappy dynamics simulator for a mission profile. Provide wing morphology, control schedule, and duration. Returns pose histories, energy metrics, and solver provenance. Example: {"scenario_id":"demo","duration_s":8.0}
Inputs: request (required). Returns: Response returned by `execute_flappy`.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool 'flappy.simulate' has a clearly defined and distinct purpose for running a Flappy dynamics simulator.
Since there is only one tool, naming consistency is inherently perfect. The tool name 'flappy.simulate' follows a clear verb_noun pattern with no deviations or mixing of conventions.
A single tool is too few for the apparent scope of a Flappy dynamics simulator server, which typically involves complex mission profiles, morphology, and control schedules. This minimal toolset feels thin and likely incomplete for the domain.
The tool surface is severely incomplete for a dynamics simulator domain. There are obvious gaps such as tools for configuring scenarios, retrieving past simulations, managing mission profiles, or analyzing results, which will cause agent failures in typical workflows.
Maintenance
Related MCP Connectors
Simulate electric UAV powertrains and search a public motor, propeller and battery database.
FlightAware MCP — wraps FlightAware AeroAPI v4 (aeroapi.flightaware.com)
Live flight status and scheduled-route search via the official FlightAware AeroAPI.
Flight and sky conditions for agents, from METAR/TAF and airports to aurora and satellite passes.
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
- AlicenseAqualityDmaintenanceEnables automated geometry editing and aerodynamic analysis using OpenVSP and VSPAero through natural language. Provides tools to modify aircraft geometry parameters and run computational fluid dynamics simulations programmatically.38MIT
- AlicenseBqualityDmaintenanceEnables wing simulation and aerodynamic analysis for pterosaur-inspired flight models. Provides lift, drag, and thrust calculations through the pterasim module with analytical fallbacks when the native module is unavailable.1MIT
- AlicenseAqualityBmaintenanceEnables running reproducible AVL 3.52 aerodynamic analyses through MCP, with input validation, isolated execution, sweeps, background jobs, and structured results including solver files.14GPL 2.0