Aerospace MCP

Aerospace MCP - Flight Planning API & MCP Server

A comprehensive aerospace research and flight planning service providing both HTTP API and Model Context Protocol (MCP) integration. Built with FastMCP for streamlined MCP server development. Features intelligent airport resolution, great-circle route calculation, aircraft performance estimation, atmospheric modeling, coordinate frame transformations, aerodynamic analysis, propeller performance modeling, rocket trajectory optimization, orbital mechanics calculations, and spacecraft trajectory planning for aerospace operations.

⚠️ SAFETY DISCLAIMER

THIS SOFTWARE IS FOR EDUCATIONAL, RESEARCH, AND DEVELOPMENT PURPOSES ONLY

NOT FOR REAL NAVIGATION: Do not use for actual flight planning or navigation
NOT CERTIFIED: This system is not certified by any aviation authority
ESTIMATES ONLY: Performance calculations are theoretical estimates
NO WEATHER DATA: Does not account for weather, NOTAMs, or airspace restrictions
NO LIABILITY: Authors assume no responsibility for any consequences of use

For real flight planning, always use certified aviation software and consult official sources including NOTAMs, weather reports, and air traffic control.

🚀 Quick Start

Option 1: UV (Recommended)

# Install UV (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/username/aerospace-mcp.git
cd aerospace-mcp
uv venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv sync

# Copy env and configure (optional but recommended)
cp .env.example .env
# Edit .env as needed (host/port/log level, optional LLM tools)

# Run HTTP server (package entrypoint)
uv run aerospace-mcp-http

# Alternatively (developer style)
uvicorn main:app --reload --host 0.0.0.0 --port 8080

# Test the API
curl "http://localhost:8080/health"

Option 2: Docker

git clone https://github.com/username/aerospace-mcp.git
cd aerospace-mcp
docker build -t aerospace-mcp .
docker run -p 8080:8080 aerospace-mcp

# Test the API
curl "http://localhost:8080/health"

Option 3: MCP Client (Claude Desktop)

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "aerospace-mcp": {
      "command": "uv",
      "args": ["run", "aerospace-mcp"],
      "cwd": "/path/to/aerospace-mcp",
      "env": {
        "LLM_TOOLS_ENABLED": "true",
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

Note: The env section is optional and only needed if you want to enable the AI-powered agent tools for enhanced user experience.

MCP via CLI

# Start the MCP server (stdio)
uv run aerospace-mcp

# Start in SSE mode (optional)
uv run aerospace-mcp sse 0.0.0.0 8001

📋 Table of Contents

✨ Features

Core Capabilities

Airport Resolution: Intelligent city-to-airport mapping with 28,000+ airports worldwide
Route Planning: Great-circle distance calculation with geodesic precision
Performance Estimation: Aircraft-specific fuel and time calculations via OpenAP
Atmospheric Modeling: ISA atmosphere profiles with optional enhanced precision
Coordinate Transformations: ECEF, ECI, geodetic frame conversions for aerospace analysis
Multiple Interfaces: HTTP REST API and Model Context Protocol (MCP) support
Real-time Processing: Sub-second response times for flight planning requests

Space & Orbital Mechanics Capabilities

🛰️ Orbital Elements & State Vectors: Convert between Keplerian elements and Cartesian state vectors
🌍 Orbit Propagation: Numerical integration with J2 perturbations using RK4 method
🗺️ Ground Track Computation: Calculate satellite ground tracks for mission planning
🔄 Hohmann Transfers: Calculate optimal two-impulse orbital transfers
🤝 Orbital Rendezvous: Plan multi-maneuver rendezvous sequences
🎯 Trajectory Optimization: Genetic algorithms and particle swarm optimization
📊 Uncertainty Analysis: Monte Carlo sampling for trajectory robustness assessment
🚀 Lambert Problem: Two-body trajectory determination for given time-of-flight

Supported Operations

✅ Airport search by city name or IATA code
✅ Flight route planning with polyline generation
✅ Aircraft performance estimation (190+ aircraft types)
✅ Fuel consumption and flight time calculations
✅ Great-circle distance calculations
✅ Multi-leg journey planning
✅ Aircraft comparison analysis
✅ Atmospheric profile calculation (ISA standard atmosphere)
✅ Wind profile modeling (logarithmic/power law)
✅ Coordinate frame transformations (ECEF, ECI, geodetic)
✅ Wing aerodynamics analysis (VLM, lifting line theory)
✅ Airfoil polar generation and database access
✅ Aircraft stability derivatives calculation
✅ Propeller performance analysis (BEMT)
✅ UAV energy optimization and endurance estimation
✅ Motor-propeller matching analysis
✅ 3DOF rocket trajectory simulation with atmosphere integration
✅ Rocket sizing estimation for mission planning
✅ Launch angle optimization for maximum performance
✅ Thrust profile optimization using gradient descent
✅ Trajectory sensitivity analysis for design studies
✅ System capability discovery and status reporting
✅ Orbital mechanics calculations (Keplerian elements, state vectors, propagation)
✅ Ground track computation for satellite tracking and visualization
✅ Hohmann transfer planning for orbital maneuvers and mission design
✅ Orbital rendezvous planning for spacecraft proximity operations
✅ Trajectory optimization using genetic algorithms and particle swarm optimization
✅ Monte Carlo uncertainty analysis for trajectory robustness assessment
✅ Lambert problem solving for two-body trajectory determination
✅ Porkchop plot generation for interplanetary transfer opportunity analysis
✅ Optional SPICE integration with fallback to simplified ephemeris models

Technical Features

🚀 Fast: In-memory airport database for microsecond lookups
🔧 Flexible: Pluggable backend system (currently OpenAP)
📊 Accurate: Uses WGS84 geodesic calculations
🌐 Standards: Follows ICAO aircraft codes and IATA airport codes
🔒 Reliable: Comprehensive error handling and graceful degradation
📚 Well-documented: Complete API documentation with examples

💾 Installation

System Requirements

Python: 3.11+ (3.12+ recommended for best performance)
Memory: 512MB RAM minimum (1GB+ recommended)
Storage: 200MB free space
Network: Internet connection for initial setup

Method 1: UV Package Manager (Recommended)

UV is the fastest Python package manager and provides excellent dependency resolution:

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh  # Linux/macOS
# Or: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

# Clone repository
git clone https://github.com/username/aerospace-mcp.git
cd aerospace-mcp

# Create virtual environment
uv venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate     # Windows

# Install dependencies
uv add fastapi uvicorn[standard] airportsdata geographiclib pydantic python-dotenv
uv add openap  # Optional: for performance estimates
uv add mcp     # Optional: for MCP server functionality

# Install optional aerospace analysis dependencies
uv add --optional-dependencies atmosphere  # Ambiance for enhanced ISA
uv add --optional-dependencies space      # Astropy for coordinate frames
uv add --optional-dependencies all        # All optional dependencies

# Install development dependencies (optional)
uv add --dev pytest httpx black isort mypy pre-commit

# Verify installation
python -c "import main; print('✅ Installation successful')"

Method 2: Pip (Traditional)

# Clone repository
git clone https://github.com/username/aerospace-mcp.git
cd aerospace-mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate     # Windows

# Upgrade pip
pip install --upgrade pip

# Install core dependencies
pip install fastapi uvicorn[standard] airportsdata geographiclib pydantic python-dotenv

# Install optional dependencies
pip install openap  # For performance estimates
pip install mcp     # For MCP server
pip install python-dotenv  # For loading .env in local/dev

# Install from pyproject.toml
pip install -e .

# Verify installation
python -c "import main; print('✅ Installation successful')"

Method 3: Docker

# Clone repository
git clone https://github.com/username/aerospace-mcp.git
cd aerospace-mcp

# Build image
docker build -t aerospace-mcp .

# Run container
docker run -d -p 8080:8080 --name aerospace-mcp aerospace-mcp

# Health check
curl http://localhost:8080/health

# View logs
docker logs aerospace-mcp

# Stop container
docker stop aerospace-mcp

Method 4: Conda/Mamba

# Create conda environment
conda create -n aerospace-mcp python=3.11
conda activate aerospace-mcp

# Clone repository
git clone https://github.com/username/aerospace-mcp.git
cd aerospace-mcp

# Install dependencies
conda install fastapi uvicorn pydantic
pip install airportsdata geographiclib openap mcp

# Verify installation
python -c "import main; print('✅ Installation successful')"

Troubleshooting Installation

Common Issues

OpenAP Installation Problems:

# Try these alternatives if OpenAP fails to install
pip install openap --no-cache-dir
pip install openap --force-reinstall
# Or install without OpenAP (performance estimates will be unavailable)

GeographicLib Issues:

# Install system dependencies (Ubuntu/Debian)
sudo apt-get install libproj-dev proj-data proj-bin

# Install system dependencies (macOS)
brew install proj

# Install system dependencies (Windows)
# Download from: https://proj.org/download.html

Import Errors:

# Verify your Python environment
python --version  # Should be 3.11+
pip list | grep -E "(fastapi|openap|airportsdata)"

# Test individual imports
python -c "import fastapi; print('FastAPI OK')"
python -c "import airportsdata; print('AirportsData OK')"
python -c "import openap; print('OpenAP OK')" || echo "OpenAP not available (optional)"

🎯 Usage Examples

HTTP API Examples

Basic Flight Planning

# Plan a simple flight
curl -X POST "http://localhost:8080/plan" \
  -H "Content-Type: application/json" \
  -d '{
    "depart_city": "San Francisco",
    "arrive_city": "New York",
    "ac_type": "A320",
    "cruise_alt_ft": 37000,
    "backend": "openap"
  }'

Airport Search

# Find airports by city
curl "http://localhost:8080/airports/by_city?city=Tokyo"

# Filter by country
curl "http://localhost:8080/airports/by_city?city=London&country=GB"

# Multiple results
curl "http://localhost:8080/airports/by_city?city=Paris"

Advanced Flight Planning

# Specify exact airports and aircraft mass
curl -X POST "http://localhost:8080/plan" \
  -H "Content-Type: application/json" \
  -d '{
    "depart_city": "Los Angeles",
    "arrive_city": "Tokyo",
    "prefer_depart_iata": "LAX",
    "prefer_arrive_iata": "NRT",
    "ac_type": "B777",
    "cruise_alt_ft": 39000,
    "mass_kg": 220000,
    "route_step_km": 100.0,
    "backend": "openap"
  }'

Python Client Examples

Simple Client

import requests
import json

class AerospaceClient:
    def __init__(self, base_url="http://localhost:8080"):
        self.base_url = base_url

    def plan_flight(self, departure, arrival, aircraft="A320", altitude=35000):
        """Plan a flight between two cities."""
        response = requests.post(f"{self.base_url}/plan", json={
            "depart_city": departure,
            "arrive_city": arrival,
            "ac_type": aircraft,
            "cruise_alt_ft": altitude,
            "backend": "openap"
        })
        return response.json()

    def find_airports(self, city, country=None):
        """Find airports in a city."""
        params = {"city": city}
        if country:
            params["country"] = country
        response = requests.get(f"{self.base_url}/airports/by_city", params=params)
        return response.json()

# Usage
client = AerospaceClient()

# Find airports
airports = client.find_airports("Sydney", "AU")
print(f"Sydney has {len(airports)} airports")

# Plan flight
plan = client.plan_flight("Sydney", "Melbourne", "B737")
print(f"Flight distance: {plan['distance_nm']:.0f} NM")
print(f"Flight time: {plan['estimates']['block']['time_min']:.0f} minutes")

Batch Processing

import asyncio
import aiohttp
from typing import List, Dict

async def plan_multiple_flights(flights: List[Dict]) -> List[Dict]:
    """Plan multiple flights concurrently."""
    async with aiohttp.ClientSession() as session:
        tasks = []
        for flight in flights:
            task = plan_single_flight(session, flight)
            tasks.append(task)

        results = await asyncio.gather(*tasks, return_exceptions=True)
        return results

async def plan_single_flight(session, flight_data):
    """Plan a single flight."""
    async with session.post(
        "http://localhost:8080/plan",
        json=flight_data
    ) as response:
        return await response.json()

# Example usage
flights_to_plan = [
    {"depart_city": "New York", "arrive_city": "London", "ac_type": "A330"},
    {"depart_city": "London", "arrive_city": "Dubai", "ac_type": "B777"},
    {"depart_city": "Dubai", "arrive_city": "Singapore", "ac_type": "A350"}
]

# Run the batch planning
results = asyncio.run(plan_multiple_flights(flights_to_plan))
for i, result in enumerate(results):
    if not isinstance(result, Exception):
        print(f"Flight {i+1}: {result['distance_nm']:.0f} NM, {result['estimates']['block']['time_min']:.0f} min")

Orbital Mechanics Examples

Python Examples

import requests

class OrbitalMechanicsClient:
    def __init__(self, base_url="http://localhost:8080"):
        self.base_url = base_url

    def plan_hohmann_transfer(self, r1_km, r2_km):
        """Calculate Hohmann transfer between two circular orbits."""
        response = requests.post(f"{self.base_url}/hohmann_transfer", json={
            "r1_m": r1_km * 1000,  # Convert to meters
            "r2_m": r2_km * 1000
        })
        return response.json()

    def propagate_satellite_orbit(self, elements, duration_hours):
        """Propagate satellite orbit with J2 perturbations."""
        response = requests.post(f"{self.base_url}/propagate_orbit_j2", json={
            "initial_state": elements,
            "time_span_s": duration_hours * 3600,
            "time_step_s": 300  # 5-minute steps
        })
        return response.json()

# Example usage
client = OrbitalMechanicsClient()

# Plan a GTO to GEO transfer
gto_alt = 200    # km (perigee)
geo_alt = 35786  # km (GEO altitude)

transfer = client.plan_hohmann_transfer(
    6378 + gto_alt,  # Earth radius + altitude
    6378 + geo_alt
)

print(f"Transfer Delta-V: {transfer['delta_v_total_ms']/1000:.2f} km/s")
print(f"Transfer Time: {transfer['transfer_time_h']:.1f} hours")

# Propagate ISS orbit for one day
iss_elements = {
    "semi_major_axis_m": 6793000,  # ~415 km altitude
    "eccentricity": 0.0001,
    "inclination_deg": 51.6,
    "raan_deg": 0.0,
    "arg_periapsis_deg": 0.0,
    "true_anomaly_deg": 0.0,
    "epoch_utc": "2024-01-01T12:00:00"
}

orbit_states = client.propagate_satellite_orbit(iss_elements, 24)
print(f"Propagated {len(orbit_states)} orbital states over 24 hours")

Trajectory Optimization Example

# Optimize a lunar transfer trajectory
def optimize_lunar_transfer():
    initial_trajectory = [
        {
            "time_s": 0,
            "position_m": [6700000, 0, 0],      # LEO
            "velocity_ms": [0, 7500, 0]
        },
        {
            "time_s": 86400 * 3,  # 3 days
            "position_m": [384400000, 0, 0],    # Moon distance
            "velocity_ms": [0, 1000, 0]
        }
    ]

    response = requests.post("http://localhost:8080/genetic_algorithm_optimization", json={
        "initial_trajectory": initial_trajectory,
        "objective": "minimize_delta_v",
        "constraints": {
            "max_thrust_n": 50000,
            "max_acceleration_ms2": 10
        }
    })

    result = response.json()
    print(f"Optimized Delta-V: {result['total_delta_v_ms']/1000:.2f} km/s")
    print(f"Flight Time: {result['flight_time_s']/86400:.1f} days")
    return result

optimized_trajectory = optimize_lunar_transfer()

# Generate porkchop plot for Mars mission planning
def plan_mars_mission():
    response = requests.post("http://localhost:8080/porkchop_plot_analysis", json={
        "departure_body": "Earth",
        "arrival_body": "Mars",
        "min_tof_days": 200,
        "max_tof_days": 300
    })

    analysis = response.json()

    if analysis["summary_statistics"]["feasible_transfers"] > 0:
        optimal = analysis["optimal_transfer"]
        print(f"Optimal Mars Transfer:")
        print(f"  Launch: {optimal['departure_date']}")
        print(f"  Arrival: {optimal['arrival_date']}")
        print(f"  C3: {optimal['c3_km2_s2']:.2f} km²/s²")
        print(f"  Flight Time: {optimal['time_of_flight_days']:.0f} days")
    else:
        print("No feasible transfers found in date range")

plan_mars_mission()

JavaScript/TypeScript Examples

interface FlightPlan {
  depart_city: string;
  arrive_city: string;
  ac_type: string;
  cruise_alt_ft?: number;
  backend: "openap";
}

class AerospaceAPI {
  constructor(private baseUrl: string = "http://localhost:8080") {}

  async planFlight(request: FlightPlan) {
    const response = await fetch(`${this.baseUrl}/plan`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(request),
    });

    if (!response.ok) {
      throw new Error(`API Error: ${response.statusText}`);
    }

    return await response.json();
  }

  async findAirports(city: string, country?: string) {
    const params = new URLSearchParams({ city });
    if (country) params.append("country", country);

    const response = await fetch(`${this.baseUrl}/airports/by_city?${params}`);
    return await response.json();
  }
}

// Usage
const api = new AerospaceAPI();

try {
  const plan = await api.planFlight({
    depart_city: "Boston",
    arrive_city: "Seattle",
    ac_type: "B737",
    cruise_alt_ft: 36000,
    backend: "openap"
  });

  console.log(`Flight planned: ${plan.distance_nm} NM`);
  console.log(`Estimated time: ${plan.estimates.block.time_min} minutes`);
} catch (error) {
  console.error("Flight planning failed:", error);
}

🏗️ Architecture

System Overview

Key Components

FastAPI Application (main.py)
- RESTful endpoints for HTTP clients
- Auto-generated OpenAPI documentation
- Request/response validation with Pydantic
MCP Server (aerospace_mcp/server.py)
- Model Context Protocol implementation
- Tool-based interface for AI assistants
- Async request handling
Core Services
- Airport Resolution: City → Airport mapping with intelligent selection
- Route Calculation: Great-circle paths with polyline generation
- Performance Estimation: OpenAP-based fuel and time calculations
Data Layer
- In-memory Airport Database: 28,000+ airports loaded at startup
- OpenAP Integration: Aircraft performance models
- GeographicLib: Precise geodesic calculations

Design Principles

Performance First: In-memory data structures for sub-millisecond lookups
Graceful Degradation: Works without optional dependencies
Type Safety: Full type hints and Pydantic validation
Extensible: Plugin architecture for new backends
Standards Compliant: ICAO, IATA, and OpenAP standards

🚀 FastMCP Migration

This project has been migrated from the traditional MCP SDK to FastMCP, providing significant improvements in developer experience and code maintainability.

What is FastMCP?

FastMCP is a high-level, Pythonic framework for building Model Context Protocol servers. It dramatically reduces boilerplate code while maintaining full MCP compatibility.

Migration Benefits

✅ 70% Less Code: Tool definitions went from verbose JSON schemas to simple Python decorators ✅ Better Type Safety: Automatic schema generation from type hints ✅ Cleaner Architecture: Modular tool organization across logical domains ✅ Improved Maintainability: Pythonic code that's easier to read and extend ✅ Full Compatibility: Same MCP protocol, works with all existing clients

Before vs After

Before (Traditional MCP SDK):

Tool(
    name="search_airports",
    description="Search for airports by IATA code or city name",
    inputSchema={
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "IATA code or city name"},
            "country": {"type": "string", "description": "Optional country filter"},
            "query_type": {"type": "string", "enum": ["iata", "city", "auto"]}
        },
        "required": ["query"]
    }
)

@server.call_tool()
async def handle_call_tool(name: str, arguments: dict):
    if name == "search_airports":
        return await _handle_search_airports(arguments)
    # ... 30+ more tool handlers

⚙️ Configuration (.env)

Both the HTTP server and MCP servers automatically load environment variables from a local .env (via python-dotenv).

AEROSPACE_MCP_MODE: http or mcp (Docker entrypoint switch)
AEROSPACE_MCP_HOST: Bind host for HTTP (default 0.0.0.0)
AEROSPACE_MCP_PORT: Port for HTTP (default 8080)
AEROSPACE_MCP_LOG_LEVEL: debug|info|warning|error (default info)
AEROSPACE_MCP_ENV: development|production (controls reload)
LLM_TOOLS_ENABLED: true|false to enable AI agent tools (default false)
OPENAI_API_KEY: Required if LLM tools are enabled

Example .env:

AEROSPACE_MCP_MODE=http
AEROSPACE_MCP_HOST=0.0.0.0
AEROSPACE_MCP_PORT=8080
AEROSPACE_MCP_LOG_LEVEL=debug
LLM_TOOLS_ENABLED=false
# OPENAI_API_KEY=sk-...

After (FastMCP):

@mcp.tool
def search_airports(
    query: str,
    country: str | None = None,
    query_type: Literal["iata", "city", "auto"] = "auto"
) -> str:
    """Search for airports by IATA code or city name."""
    # Implementation here

Architecture Improvements

The FastMCP refactoring introduced a modular architecture with tools organized by domain:

tools/core.py - Core flight planning (search, plan, distance, performance)
tools/atmosphere.py - Atmospheric modeling and wind analysis
tools/frames.py - Coordinate frame transformations
tools/aerodynamics.py - Wing analysis and airfoil polars
tools/propellers.py - Propeller BEMT and UAV energy analysis
tools/rockets.py - Rocket trajectory and sizing
tools/orbits.py - Orbital mechanics and propagation
tools/optimization.py - Trajectory optimization algorithms

Compatibility Notes

Entry Point: Now uses aerospace_mcp.fastmcp_server:run
Dependencies: Includes fastmcp>=2.11.3 instead of raw mcp
Server Name: Still aerospace-mcp for client compatibility
All Tools: All 30+ tools maintain exact same names and parameters

⚡ Performance

Benchmarks

Operation	Response Time	Throughput	Memory Usage
Health Check	< 1ms	10,000+ req/sec	~5MB
Airport Search	1-5ms	1,000+ req/sec	~50MB
Flight Planning	200-500ms	5-10 req/sec	~100MB
Distance Calc	10-50ms	100+ req/sec	~50MB

Optimization Tips

Route Resolution: Use larger route_step_km values for faster processing
Caching: Implement client-side caching for repeated requests
Batch Processing: Use async clients for multiple concurrent requests
Memory: Increase available RAM for better OpenAP performance

Scaling Considerations

Horizontal Scaling: Stateless design allows multiple instances
Load Balancing: Standard HTTP load balancers work well
Database: Consider external database for airport data at scale
Caching: Add Redis for shared cache across instances

📖 API Documentation

Interactive Documentation

When running the server, comprehensive API documentation is available at:

Swagger UI: http://localhost:8080/docs
ReDoc: http://localhost:8080/redoc
OpenAPI Schema: http://localhost:8080/openapi.json

Core Endpoints

GET /health

Health check and system status.

Response:

{
  "status": "ok",
  "openap": true,
  "airports_count": 28756
}

GET /airports/by_city

Search airports by city name.

Parameters:

city (required): City name to search
country (optional): ISO country code filter

Example: GET /airports/by_city?city=London&country=GB

POST /plan

Generate complete flight plan.

Request Body:

{
  "depart_city": "San Francisco",
  "arrive_city": "New York",
  "ac_type": "A320",
  "cruise_alt_ft": 37000,
  "mass_kg": 65000,
  "route_step_km": 25.0,
  "backend": "openap"
}

Response: Complete flight plan with route polyline and performance estimates.

Error Handling

All endpoints return standard HTTP status codes:

200: Success
400: Bad Request (invalid parameters)
404: Not Found (airport/city not found)
501: Not Implemented (backend unavailable)

Error responses include detailed messages:

{
  "detail": "departure: IATA 'XYZ' not found."
}

🤖 MCP Integration

Supported MCP Clients

Claude Desktop: Native integration
VS Code Continue: Plugin support
Custom Clients: Standard MCP protocol

Available Tools

Tool	Description	Parameters
`search_airports`	Find airports by IATA or city	`query`, `country`, `query_type`
`plan_flight`	Complete flight planning	`departure`, `arrival`, `aircraft`, `route_options`
`calculate_distance`	Great-circle distance	`origin`, `destination`, `step_km`
`get_aircraft_performance`	Performance estimates	`aircraft_type`, `distance_km`, `cruise_altitude`
`get_atmosphere_profile`	ISA atmosphere conditions	`altitudes_m`, `model_type`
`wind_model_simple`	Wind profile calculation	`altitudes_m`, `surface_wind_mps`, `model`
`transform_frames`	Coordinate transformations	`xyz`, `from_frame`, `to_frame`, `epoch_iso`
`geodetic_to_ecef`	Lat/lon to ECEF conversion	`latitude_deg`, `longitude_deg`, `altitude_m`
`ecef_to_geodetic`	ECEF to lat/lon conversion	`x`, `y`, `z`
`wing_vlm_analysis`	Wing aerodynamics analysis (VLM)	`geometry`, `alpha_deg_list`, `mach`
`airfoil_polar_analysis`	Airfoil polar generation	`airfoil_name`, `alpha_deg_list`, `reynolds`, `mach`
`calculate_stability_derivatives`	Stability derivatives calculation	`geometry`, `alpha_deg`, `mach`
`propeller_bemt_analysis`	Propeller performance (BEMT)	`geometry`, `rpm_list`, `velocity_ms`, `altitude_m`
`uav_energy_estimate`	UAV endurance and energy analysis	`uav_config`, `battery_config`, `mission_profile`
`get_airfoil_database`	Available airfoil coefficients	None
`get_propeller_database`	Available propeller data	None
`rocket_3dof_trajectory`	3DOF rocket trajectory simulation	`geometry`, `dt_s`, `max_time_s`, `launch_angle_deg`
`estimate_rocket_sizing`	Rocket sizing for mission requirements	`target_altitude_m`, `payload_mass_kg`, `propellant_type`
`optimize_launch_angle`	Launch angle optimization	`geometry`, `objective`, `angle_bounds`
`optimize_thrust_profile`	Thrust profile optimization	`geometry`, `burn_time_s`, `total_impulse_target`, `n_segments`, `objective`
`trajectory_sensitivity_analysis`	Parameter sensitivity analysis	`base_geometry`, `parameter_variations`, `objective`
`get_system_status`	System health and capabilities	None
`elements_to_state_vector`	Convert orbital elements to state vector	`elements`
`state_vector_to_elements`	Convert state vector to orbital elements	`state_vector`
`propagate_orbit_j2`	Propagate orbit with J2 perturbations	`initial_state`, `time_span_s`, `time_step_s`
`calculate_ground_track`	Calculate satellite ground track	`orbit_states`, `time_step_s`
`hohmann_transfer`	Calculate Hohmann transfer orbit	`r1_m`, `r2_m`
`orbital_rendezvous_planning`	Plan orbital rendezvous maneuvers	`chaser_elements`, `target_elements`
`genetic_algorithm_optimization`	Trajectory optimization using GA	`initial_trajectory`, `objective`, `constraints`
`particle_swarm_optimization`	Trajectory optimization using PSO	`initial_trajectory`, `objective`, `constraints`
`monte_carlo_uncertainty_analysis`	Monte Carlo trajectory uncertainty analysis	`trajectory`, `uncertainty_params`, `num_samples`
`porkchop_plot_analysis`	Generate porkchop plot for interplanetary transfers	`departure_body`, `arrival_body`, `departure_dates`, `arrival_dates`, `min_tof_days`, `max_tof_days`

Claude Desktop Setup

Open Claude Desktop Settings
Add server configuration:

{
  "mcpServers": {
    "aerospace-mcp": {
      "command": "python",
      "args": ["-m", "aerospace_mcp.server"],
      "cwd": "/path/to/aerospace-mcp",
      "env": {
        "PYTHONPATH": "/path/to/aerospace-mcp"
      }
    }
  }
}

Restart Claude Desktop
Test with: "Search for airports in Tokyo"

VS Code Continue Setup

Add to your config.json:

{
  "mcpServers": [
    {
      "name": "aerospace-mcp",
      "command": "python",
      "args": ["-m", "aerospace_mcp.server"],
      "workingDirectory": "/path/to/aerospace-mcp"
    }
  ]
}

🛠️ Development

Development Setup

# Clone and setup
git clone https://github.com/username/aerospace-mcp.git
cd aerospace-mcp

# Create development environment
uv venv
source .venv/bin/activate
uv add --dev pytest httpx black isort mypy pre-commit

# Install pre-commit hooks
pre-commit install

# Run development server
uvicorn main:app --reload --log-level debug

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=. --cov-report=html

# Run specific test file
pytest tests/test_main.py -v

# Performance testing
pytest tests/test_performance.py -v

Code Quality

# Format code
black . && isort .

# Type checking
mypy main.py aerospace_mcp/

# Linting
ruff check .

# Pre-commit (runs all checks)
pre-commit run --all-files

Project Structure

aerospace-mcp/
├── main.py                 # FastAPI application
├── aerospace_mcp/          # MCP server implementation
│   ├── __init__.py
│   ├── server.py          # MCP server
│   └── core.py            # Shared business logic
├── app/                   # Alternative FastAPI structure
│   ├── __init__.py
│   └── main.py
├── tests/                 # Test suite
│   ├── conftest.py
│   ├── test_main.py
│   ├── test_airports.py
│   ├── test_plan.py
│   └── test_mcp.py
├── docs/                  # Documentation
│   ├── API.md
│   ├── ARCHITECTURE.md
│   ├── INTEGRATION.md
│   ├── QUICKSTART.md
│   ├── DEPLOYMENT.md
│   └── MCP_INTEGRATION.md
├── pyproject.toml         # Project configuration
├── requirements.txt       # Dependencies
├── Dockerfile            # Docker configuration
├── docker-compose.yml    # Multi-service setup
└── README.md             # This file

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines.

Quick Contributing Guide

Fork & Clone
git clone https://github.com/yourusername/aerospace-mcp.git cd aerospace-mcp
Setup Development Environment
uv venv && source .venv/bin/activate uv add --dev pytest httpx black isort mypy
Make Changes
- Add features or fix bugs
- Write tests for new functionality
- Update documentation as needed
Test & Format
pytest black . && isort . mypy main.py
Submit Pull Request
- Clear title and description
- Reference any related issues
- Ensure CI/CD checks pass

Areas for Contribution

New Aircraft Support: Add more aircraft types to OpenAP
Weather Integration: Add weather data sources
Route Optimization: Implement waypoint optimization
UI/Frontend: Web interface for flight planning
Database Backend: PostgreSQL/MongoDB integration
Performance: Optimization and caching improvements

📚 Documentation

Complete Documentation

Quick Start Guide - Get up and running in 5 minutes
API Reference - Complete REST API documentation
MCP Integration - Model Context Protocol setup
Architecture Guide - System design and components
Deployment Guide - Production deployment strategies
Contributing Guide - Development and contribution guidelines
Integration Guide - Client integration examples

Examples Repository

Check out the examples repository for:

Complete client implementations
Integration patterns
Performance benchmarks
Real-world use cases

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Third-Party Acknowledgments

OpenAP: Aircraft performance modeling - TU Delft
AirportsData: Airport database - mborsetti
GeographicLib: Geodesic calculations - Charles Karney
FastAPI: Modern web framework - Sebastián Ramírez

🆘 Support & Community

Getting Help

GitHub Issues: Bug reports and feature requests
GitHub Discussions: Questions and community support
Documentation: Comprehensive guides in /docs
Examples: Code examples and tutorials

Community

Discord: WIP for real-time chat

Professional Support

For enterprise support, consulting, or custom development:

Email: hello@aeroastro.org
Website: https://aeroastro.org

⭐ Star this repository if you find it useful!

Built with ❤️ for the aviation and software development communities.

Deploy Server

HTTP connection URL

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

Enables flight planning and aviation operations through intelligent airport resolution, great-circle route calculation, and aircraft performance estimation. Supports 28,000+ airports worldwide and 190+ aircraft types for comprehensive flight planning via natural language.

Related MCP Servers

Flight Planner MCP Server
salamentic
-
security
F
license
-
quality
Creates travel agent-level flight plans using the fast-flights API, allowing users to search for flights and generate comprehensive travel itineraries.
Last updated -
5
Aviation Model Context Protocol
blevinstein
A
security
F
license
A
quality
Integration platform for aviation data sources including weather, NOTAMs, airport information, and flight planning APIs, enabling comprehensive pre-flight preparation and in-flight decision support.
Last updated -
1
0
2
Variflight Tripmatch MCP Serverofficial
variflight
A
security
F
license
A
quality
Provides tools to query flight and train information including flight searches, train tickets, weather forecasts, and transfer options between different transportation modes.
Last updated -
9
11
Flight Ticket MCP Server
xiaonieli7
-
security
A
license
-
quality
A server that provides real-time flight information query capabilities to AI assistants, allowing them to access detailed flight statuses, airport details, and related travel information.
Last updated -
10
8
MIT License

View all related MCP servers