Aviation MCP Server

A FastMCP server that provides real-time aircraft data from ADS-B Exchange (adsb.lol API) via Streamable HTTP transport.

Features

🚀 Streamable HTTP Transport - Modern HTTP with JSON-RPC protocol
🔐 API Key Authentication - Secure access control
⚡ FastMCP Framework - High-performance MCP server
🛫 Real-time Aircraft Data - Live ADS-B data from adsb.lol
📡 Multiple Query Types - 8 different ways to query aircraft data
🐳 Production Ready - Can run standalone or in containers

Quick Start

Installation

cd aviation-mcp-server
uv sync

Running the Server

Development: ``bash uv run aviation-mcp-server-http ``

With Custom Configuration: ``bash export MCP_HOST="0.0.0.0" export MCP_PORT="8000" export MCP_API_KEY="your-secret-key" uv run aviation-mcp-server-http ``

The server will start on http://0.0.0.0:8000/mcp

Configuration

Environment variables:

MCP_HOST=0.0.0.0                          # Server bind address (default: 0.0.0.0)
MCP_PORT=8000                             # Server port (default: 8000)
MCP_API_KEY=your-secret-key               # API key for authentication (default: dev key)

API Documentation

Endpoint

URL: http://localhost:8000/mcp
Method: POST
Content-Type: application/json
Accept: application/json, text/event-stream

Authentication

Include API key in one of these headers:

X-API-Key: your-secret-key
Authorization: Bearer your-secret-key

Available Tool: `query_aircraft`

Query real-time aircraft data from ADS-B Exchange.

Parameters

query_type (required): Type of query
"callsign": Search by flight callsign (e.g., "UAL123")
"registration": Search by aircraft registration (e.g., "N12345")
"aircraft_type": Search by aircraft type (e.g., "B738", "A320")
"icao_hex": Search by ICAO hex code
"squawk": Search by transponder squawk code (e.g., "7700")
"location": Search within radius of coordinates
"military": Get all military aircraft
"privacy": Get aircraft with privacy ICAO addresses

value (optional): Search value for most query types
latitude (optional): Latitude for location queries (-90 to 90)
longitude (optional): Longitude for location queries (-180 to 180)
radius (optional): Search radius in nautical miles for location queries

Example Requests

List Available Tools: ``bash curl -X POST http://localhost:8000/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "X-API-Key: adsb-mcp-secret-key-change-in-production" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }' ``

Query Military Aircraft: ``bash curl -X POST http://localhost:8000/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "X-API-Key: adsb-mcp-secret-key-change-in-production" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "query_aircraft", "arguments": { "query_type": "military" } } }' ``

Query by Callsign: ``bash curl -X POST http://localhost:8000/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "X-API-Key: adsb-mcp-secret-key-change-in-production" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "query_aircraft", "arguments": { "query_type": "callsign", "value": "UAL123" } } }' ``

Query by Location: ``bash curl -X POST http://localhost:8000/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "X-API-Key: adsb-mcp-secret-key-change-in-production" \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "query_aircraft", "arguments": { "query_type": "location", "latitude": 40.7128, "longitude": -74.0060, "radius": 50 } } }' ``

Testing

Test Server Connectivity

uv run python test_server.py

This will:

Test military aircraft query
Test callsign query
Verify API connectivity

Manual Health Check

curl -I http://localhost:8000/mcp

Expected: 405 Method Not Allowed (GET not supported, use POST)

Integration

Discord Bot

The aviation-discord-bot project can connect to this server:

MCP_TRANSPORT=http
MCP_SERVER_URL=http://localhost:8000/mcp
MCP_API_KEY=your-secret-key

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "adsb-aircraft-data": {
      "command": "bash",
      "args": ["-c", "cd /path/to/aviation-mcp-server && uv run aviation-mcp-server-http"],
      "env": {
        "MCP_API_KEY": "your-secret-key"
      }
    }
  }
}

Other MCP Clients

Any MCP client supporting HTTP transport can connect using:

Transport: HTTP
URL: http://localhost:8000/mcp
Protocol: JSON-RPC 2.0
Authentication: API key via X-API-Key header

Architecture

┌────────────────┐
│  MCP Client    │
│  (Bot/Claude)  │
└────────┬───────┘
         │
         │ HTTP POST + JSON-RPC
         │ + X-API-Key header
         │
         ▼
┌────────────────┐
│  FastMCP       │
│  + uvicorn     │
│  + Auth        │
└────────┬───────┘
         │
         │ HTTPS
         │
         ▼
┌────────────────┐
│  adsb.lol API  │
│  (ADS-B Data)  │
└────────────────┘

Deployment

Docker

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install uv && uv sync
ENV MCP_API_KEY=${MCP_API_KEY}
ENV MCP_HOST=0.0.0.0
ENV MCP_PORT=8000
EXPOSE 8000
CMD ["uv", "run", "aviation-mcp-server-http"]

Build and run: ``bash docker build -t aviation-mcp-server . docker run -p 8000:8000 -e MCP_API_KEY=your-secret-key aviation-mcp-server ``

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aviation-mcp-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: aviation-mcp-server
  template:
    metadata:
      labels:
        app: aviation-mcp-server
    spec:
      containers:
      - name: server
        image: aviation-mcp-server:latest
        ports:
        - containerPort: 8000
        env:
        - name: MCP_API_KEY
          valueFrom:
            secretKeyRef:
              name: mcp-secrets
              key: api-key
---
apiVersion: v1
kind: Service
metadata:
  name: aviation-mcp-server
spec:
  selector:
    app: aviation-mcp-server
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

systemd Service

Create /etc/systemd/system/aviation-mcp-server.service:

[Unit]
Description=Aviation MCP Server
After=network.target

[Service]
Type=simple
User=adsb
WorkingDirectory=/opt/aviation-mcp-server
Environment="MCP_API_KEY=your-secret-key"
Environment="MCP_HOST=0.0.0.0"
Environment="MCP_PORT=8000"
ExecStart=/usr/local/bin/uv run aviation-mcp-server-http
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start: ``bash sudo systemctl enable aviation-mcp-server sudo systemctl start aviation-mcp-server sudo systemctl status aviation-mcp-server ``

Security

Production Recommendations

Use HTTPS: Deploy behind reverse proxy (nginx, Caddy) with TLS
Secure API Keys: Use secrets management (AWS Secrets Manager, HashiCorp Vault)
Rate Limiting: Implement rate limiting to prevent abuse
Monitoring: Add logging and metrics (Prometheus, Grafana)
IP Filtering: Restrict access to known client IPs
Regular Updates: Keep dependencies updated

Example nginx Configuration

upstream adsb_mcp {
    server 127.0.0.1:8000;
}

server {
    listen 443 ssl http2;
    server_name mcp.example.com;

    ssl_certificate /etc/ssl/certs/mcp.crt;
    ssl_certificate_key /etc/ssl/private/mcp.key;

    location /mcp {
        proxy_pass http://adsb_mcp;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Rate limiting
        limit_req zone=mcp_limit burst=10 nodelay;
    }
}

Troubleshooting

Server won't start

Check if port 8000 is already in use: lsof -i :8000
Verify dependencies: uv sync
Check Python version: python --version (requires 3.10+)

Authentication errors

Verify API key in request headers
Check server logs for authentication failures
Ensure API key matches MCP_API_KEY environment variable

API errors

Verify internet connectivity to adsb.lol
Check adsb.lol API status
Review server logs for error details

Performance issues

Monitor server resources (CPU, memory)
Check network latency to adsb.lol API
Consider implementing caching

Development

Project Structure

aviation-mcp-server/
├── src/
│   └── aviation_mcp_server/
│       ├── __init__.py
│       └── server.py          # Main server implementation
├── pyproject.toml             # Dependencies
├── .python-version            # Python version (3.12)
├── README.md                  # This file
└── test_server.py             # Connectivity tests

Adding New Tools

To add a new MCP tool, edit server.py:

@mcp.tool()
async def your_new_tool(param1: str, param2: int) -> str:
    """
    Description of your tool.

    Args:
        param1: Description
        param2: Description

    Returns:
        Result description
    """
    # Implementation
    return "result"

Running Tests

# Test server connectivity
uv run python test_server.py

# Manual API test
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: adsb-mcp-secret-key-change-in-production" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

API Data Source

This server uses the adsb.lol API, which provides:

Real-time aircraft positions
Flight information (callsign, altitude, speed)
Aircraft details (type, registration)
Military aircraft tracking
Worldwide coverage

License

MIT

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

For issues or questions:

Check the troubleshooting section
Review server logs
Test with manual curl requests
Verify environment variables

Acknowledgments

ADS-B data: Provided by adsb.lol
MCP Framework: FastMCP
MCP Specification: Model Context Protocol

---

Version: 0.1.0 Status: Production Ready Last Updated: 2025-10-12

Aviation MCP Server