Skip to main content
Glama
lichen911

Aviation MCP Server

by lichen911
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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

Related MCP server: adsb.lol MCP Server

Quick Start

Installation

cd aviation-mcp-server
uv sync

Running the Server

Development:

uv run aviation-mcp-server-http

With Custom Configuration:

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:

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:

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:

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:

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:

  1. Test military aircraft query

  2. Test callsign query

  3. 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:

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:

sudo systemctl enable aviation-mcp-server
sudo systemctl start aviation-mcp-server
sudo systemctl status aviation-mcp-server

Security

Production Recommendations

  1. Use HTTPS: Deploy behind reverse proxy (nginx, Caddy) with TLS

  2. Secure API Keys: Use secrets management (AWS Secrets Manager, HashiCorp Vault)

  3. Rate Limiting: Implement rate limiting to prevent abuse

  4. Monitoring: Add logging and metrics (Prometheus, Grafana)

  5. IP Filtering: Restrict access to known client IPs

  6. 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:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests if applicable

  5. 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

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

Install Server
F
license - not found
A
quality
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lichen911/aviation-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server