Airplane.Live MCP Server

Servidor MCP que se conecta a la API de Airplanes.live para proporcionar datos de vuelo y aeronaves en tiempo real para análisis o visualización.

GitHub
9
Prueba este MCPPatrocinado

Documentación

✈️ Servidor MCP de Rastreo de Aviones

Python MCP License API

Airplane Tracker Banner

🎯 Descripción General

Este servidor MCP se integra con la API de airplanes.live para proporcionar capacidades de rastreo de aeronaves en tiempo real a Claude Desktop. ¡Rastrea vuelos, encuentra aeronaves por indicativo, matrícula o posición, todo directamente desde Claude!

⚠️ Aviso Importante - Términos de Uso

📖 Solo para Uso Educativo y No Comercial

Este proyecto utiliza la API de airplanes.live que se proporciona solo con fines educativos y no comerciales. Por favor, respeta sus términos de servicio.

📋 Pautas de Uso:

  • ✅ Proyectos educativos - Aprendizaje e investigación
  • ✅ Uso personal - Rastreo no comercial
  • ✅ Contribuciones de código abierto - Desarrollo comunitario
  • ❌ Aplicaciones comerciales - Fines comerciales/de lucro
  • ❌ Solicitudes de alto volumen - Respeta los límites de velocidad

🛡️ Descargo de Responsabilidad:

El autor de este servidor MCP no asume ninguna responsabilidad por el uso de este software. Esta es una contribución comunitaria destinada a fines educativos y para demostrar el desarrollo de servidores MCP. Los usuarios son responsables de cumplir con los términos de la API de airplanes.live y cualquier regulación aplicable.

🌐 Respeto por los Servicios Existentes:

Este proyecto NO pretende reemplazar ni competir con el visor global oficial de airplanes.live. El globo oficial es la forma principal y recomendada de visualizar datos de vuelo. Este servidor MCP está diseñado como una herramienta educativa complementaria para la integración con Claude Desktop y el aprendizaje del desarrollo MCP.

📖 Términos Completos de la API: https://airplanes.live/api-guide/
🌍 Visor Global Oficial: https://globe.airplanes.live

📸 Capturas de Pantalla

Claude Desktop with Airplane Tracker Rastreo de aviones en tiempo real en Claude Desktop

🚀 Características

  • 🔍 Búsqueda por Indicativo - Encuentra vuelos específicos (ej., UAL123)
  • 📋 Búsqueda por Matrícula - Rastrea por número de cola (ej., N12345)
  • 🎯 Búsqueda por Posición - Aeronaves cerca de coordenadas
  • 🏷️ Búsqueda por ID Hex - Códigos de transpondedor Modo S
  • 🛡️ Aeronaves Militares - Vuelos militares rastreados
  • 🚁 Aeronaves LADD - Rastreo de aplicación de la ley
  • ⭐ Aeronaves PIA - Aeronaves privadas/interesantes
  • 📡 Códigos Squawk - Códigos de emergencia y especiales

Varios ejemplos de búsqueda en la API

🏗️ Arquitectura

🔧 Componentes

  • 🐍 Servidor MCP en Python - Implementación de servidor asíncrono
  • 🌐 Marco MCP - Arquitectura de servidor moderna
  • ⚡ Cliente httpx - Solicitudes HTTP de alto rendimiento
  • 📊 Formateador de Datos - Información de aeronaves limpia y legible
  • 🔌 Integración con Claude - Soporte directo del protocolo MCP

📊 Flujo de Datos

graph TD
    A[Claude Desktop] --> B[MCP Protocol]
    B --> C[airplane_server.py]
    C --> D[API Functions]
    D --> E[airplanes.live API]
    E --> F[Aircraft Data]
    F --> G[Formatted Response]
    G --> A

Arquitectura del sistema y flujo de datos

🚀 Inicio Rápido

📋 Requisitos Previos

  • 🐍 Python 3.8+
  • 💻 Claude Desktop
  • 🌐 Conexión a Internet

⚡ Instalación

# 1. Clone the repository
git clone https://github.com/Bellaposa/airplanes-live-mcp.git
cd airplanes-live-mcp

# 2. Create virtual environment (REQUIRED!)
python -m venv .venv

# 3. Activate virtual environment
# macOS/Linux:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Test the server
python airplane_server.py

⚠️ Problemas Comunes y Soluciones

🔥 ¡El Entorno Virtual es OBLIGATORIO!

  • Si omites los pasos 2-3, obtendrás ModuleNotFoundError: No module named 'httpx'
  • Claude Desktop necesita la ruta completa al Python del venv, no al Python del sistema
  • Sin venv, las dependencias no están aisladas y las cosas se rompen

🪟 Usuarios de Windows:

  • El entorno virtual crea la carpeta .venv\Scripts\ (no .venv\bin\)
  • Usa Scripts\python.exe en la configuración de Claude, no bin/python
  • Usa siempre dobles barras invertidas \\ en las rutas JSON

🐍 Problemas con la Ruta de Python:

  • Asegúrate de que Python 3.8+ esté instalado: python --version
  • Si python no funciona, prueba con python3 o py
  • El entorno virtual DEBE existir antes de configurar Claude Desktop

🐳 Instalación con Docker (Alternativa)

¡Evita los problemas de configuración de Python - usa Docker!

📋 Requisitos Previos

  • 🐳 Docker Desktop instalado y ejecutándose
  • 💻 Claude Desktop

⚡ Configuración de Docker

# 1. Clone the repository
git clone https://github.com/Bellaposa/airplanes-live-mcp.git
cd airplanes-live-mcp

# 2. Build Docker image
docker build -t airplane-mcp-server .

# 3. Test the container
docker run --rm -it airplane-mcp-server python airplane_server.py

⚙️ Configuración de Claude Desktop para Docker

🍎 macOS/Linux con Docker

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "airplanes-live": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", 
        "airplane-mcp-server", 
        "python", "airplane_server.py"
      ]
    }
  }
}

🪟 Windows con Docker

Añade a %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "airplanes-live": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", 
        "airplane-mcp-server", 
        "python", "airplane_server.py"
      ]
    }
  }
}

🔄 Referencia de Comandos de Docker

# Build the image
docker build -t airplane-mcp-server .

# Run interactively for testing
docker run --rm -it airplane-mcp-server bash

# Check if image exists
docker images | grep airplane-mcp-server

# Remove image if needed
docker rmi airplane-mcp-server

# View container logs (if running detached)
docker logs <container_id>

✅ Ventajas de Docker

  • 🚀 No se requiere configuración de Python - Todo preconfigurado
  • 🔒 Entorno aislado - Sin conflictos de dependencias
  • 🌍 Funciona en todas partes - Misma configuración en Windows/Mac/Linux
  • 📦 Actualizaciones fáciles - Solo reconstruye la imagen
  • 🛡️ Comportamiento consistente - Elimina el "funciona en mi máquina"

⚠️ Solución de Problemas de Docker

Problema: "docker: command not found"

# Install Docker Desktop first
# macOS: https://docs.docker.com/desktop/install/mac-install/
# Windows: https://docs.docker.com/desktop/install/windows-install/
# Linux: https://docs.docker.com/desktop/install/linux-install/

Problema: "Cannot connect to Docker daemon"

# Start Docker Desktop application
# Wait for Docker to fully start (green icon)

Problema: "Permission denied" (Linux)

# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in, or:
newgrp docker

Problema: La construcción de la imagen falla

# Clean Docker cache
docker system prune -a
# Try building again
docker build --no-cache -t airplane-mcp-server .

🎯 Aún Más Fácil: Docker Compose

Para la configuración más simple, usa Docker Compose:

# 1. Clone and enter directory
git clone https://github.com/Bellaposa/airplanes-live-mcp.git
cd airplanes-live-mcp

# 2. Build and run with one command
docker-compose up --build

# 3. In another terminal, test the server
docker-compose exec airplane-mcp-server python airplane_server.py

Configuración de Claude con Docker Compose:

{
  "mcpServers": {
    "airplanes-live": {
      "command": "docker-compose", 
      "args": [
        "-f", "/path/to/airplanes-live-mcp/docker-compose.yml",
        "exec", "-T", "airplane-mcp-server", 
        "python", "airplane_server.py"
      ],
      "cwd": "/path/to/airplanes-live-mcp"
    }
  }
}

🐳 Cómo Usar con Claude Desktop

Método 1: Ejecución Simple de Docker

Configuración para todas las plataformas:

{
  "mcpServers": {
    "airplanes-live": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", 
        "airplane-mcp-server", 
        "python", "airplane_server.py"
      ]
    }
  }
}

Método 2: Docker Compose (Avanzado)

Configuración con rutas completas:

{
  "mcpServers": {
    "airplanes-live": {
      "command": "docker-compose",
      "args": [
        "-f", "/full/path/to/your/airplanes-live-mcp/docker-compose.yml",
        "exec", "-T", "airplane-mcp-server", 
        "python", "airplane_server.py"
      ],
      "cwd": "/full/path/to/your/airplanes-live-mcp"
    }
  }
}

Pasos Completos de Configuración de Docker:

# 1. Clone and build
git clone https://github.com/Bellaposa/airplanes-live-mcp.git
cd airplanes-live-mcp
docker build -t airplane-mcp-server .

# 2. Configure Claude Desktop with Method 1 (above)

# 3. Restart Claude Desktop completely

# 4. Test with: "Show me aircraft near New York"

🎯 Comparación Docker vs Python:

MétodoVentajasDesventajasMejor Para
Docker✅ Sin configuración de Python
✅ Funciona en todas partes
✅ Aislado		❌ Requiere Docker
❌ Ligera sobrecarga		Principiantes, usuarios de Windows
Python✅ Ejecución directa
✅ Depuración fácil
✅ Sin necesidad de Docker		❌ Configuración manual de Python
❌ Problemas específicos del SO		Desarrolladores, usuarios experimentados

Comandos de Docker Compose:

# Start services in background
docker-compose up -d

# View logs
docker-compose logs airplane-mcp-server

# Stop services
docker-compose down

# Rebuild and restart
docker-compose up --build


### ⚙️ Claude Desktop Configuration

#### 🍎 **macOS/Linux Configuration**

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/claude-desktop/config.json` (Linux):

```json
{
  "mcpServers": {
    "airplanes-live": {
      "command": "/path/to/airplanes-live-mcp/.venv/bin/python",
      "args": ["/path/to/airplanes-live-mcp/airplane_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/airplanes-live-mcp"
      }
    }
  }
}

🪟 Configuración para Windows

Añade a %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "airplanes-live": {
      "command": "C:\\Users\\YourUsername\\airplanes-live-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\YourUsername\\airplanes-live-mcp\\airplane_server.py"],
      "env": {
        "PYTHONPATH": "C:\\Users\\YourUsername\\airplanes-live-mcp"
      }
    }
  }
}

⚠️ Notas Importantes para Windows:

  • Usa Scripts\\python.exe (no bin/python)
  • Reemplaza YourUsername con tu nombre de usuario real de Windows
  • Usa dobles barras invertidas \\ en las rutas
  • Asegúrate de que el entorno virtual se cree con python -m venv .venv

Configuración de Claude Desktop

🎮 Ejemplos de Uso

Búsqueda por Indicativo

🔍 Find flight UAL123

Búsqueda por Posición Cercana

📍 Show aircraft near 40.7128, -74.0060 within 50nm

Aeronaves Militares

🛡️ Show all military aircraft

🔧 Decisiones Clave de Diseño

1. Implementación Asíncrona

Todas las herramientas usan async para manejar múltiples solicitudes de manera eficiente:

@mcp.tool()
async def aircraft_near_position(latitude: str = "", longitude: str = "", radius: str = "250") -> str:

Esto permite que el servidor maneje solicitudes concurrentes sin bloqueo.

2. Parámetros Basados en Cadenas

Todos los parámetros son cadenas porque los protocolos MCP funcionan mejor con tipos simples:

# Correct
def tool(param: str = "") -> str:

# Avoid
def tool(param: Optional[int] = None) -> str:

3. Manejo de Errores

Cada herramienta incluye manejo integral de errores:

try:
    # Main logic
except ValueError:
    return f"❌ Error: Invalid input"
except Exception as e:
    return f"❌ Error: {str(e)}"

4. Formato de Datos

La función format_aircraft_data() proporciona una salida consistente y legible:

def format_aircraft_data(aircraft_data):
    # Handles both single aircraft and lists
    # Formats all available fields with emoji indicators
    # Returns human-readable strings

5. Envoltorio de API

La función make_api_request() centraliza la lógica HTTP:

async def make_api_request(endpoint):
    async with httpx.AsyncClient(timeout=15) as client:
        url = f"{API_BASE_URL}{endpoint}"
        response = await client.get(url)
        response.raise_for_status()
        return response.json()

Este enfoque:

  • Centraliza el manejo de errores
  • Gestiona los tiempos de espera
  • Registra todas las solicitudes
  • Facilita agregar autenticación más adelante

Referencia de Herramientas

aircraft_by_hex(hex_id: str = "")

Propósito: Buscar aeronaves por identificador hex Modo S

Entrada: IDs hex separados por comas (ej., "45211e,45212f")

Devuelve: Lista de aeronaves coincidentes con detalles completos

Ejemplo:

User: "Show me aircraft with hex 45211e"
Tool: "🔍 Found 1 aircraft: ✈️ Callsign: RYR123 ..."

aircraft_by_callsign(callsign: str = "")

Propósito: Buscar aeronaves por indicativo de vuelo

Entrada: Indicativos separados por comas (ej., "BA387,AA123")

Devuelve: Aeronaves que coinciden con el indicativo

Ejemplo:

User: "Find flight BA387"
Tool: "🔍 Found 1 aircraft: ✈️ Callsign: BA387 ..."

aircraft_by_registration(reg: str = "")

Propósito: Buscar aeronaves por número de cola/matrícula

Entrada: Matrículas separadas por comas (ej., "N123AB,G-EUPA")

Devuelve: Aeronaves que coinciden con la matrícula

Ejemplo:

User: "Show aircraft with tail N123AB"
Tool: "🔍 Found 1 aircraft: 📋 Registration: N123AB ..."

aircraft_by_type(icao_type: str = "")

Propósito: Buscar aeronaves por código de tipo ICAO

Entrada: Códigos de tipo (A321, B738, C172, E190, etc.)

Devuelve: Todas las aeronaves de ese tipo actualmente en vuelo

Ejemplo:

User: "Show all Boeing 737s"
Tool: "🔍 Found 247 aircraft of type B738: ..."

aircraft_by_squawk(squawk_code: str = "")

Propósito: Buscar aeronaves por código squawk

Entrada: Código squawk de 4 dígitos (ej., "7500", "7600", "7700")

Devuelve: Aeronaves que emiten ese código

Nota: 7700 = Emergencia, 7600 = Fallo de comunicaciones, 7500 = Secuestro

Ejemplo:

User: "Find aircraft squawking 7700"
Tool: "🔍 Found aircraft in emergency: ..."

aircraft_near_position(latitude: str = "", longitude: str = "", radius: str = "250")

Propósito: Encontrar todas las aeronaves dentro de un radio de coordenadas

Entrada:

  • latitude (grados decimales, -90 a 90)
  • longitude (grados decimales, -180 a 180)
  • radius (millas náuticas, máximo 250)

Devuelve: Todas las aeronaves dentro del radio

Ejemplo:

User: "Show aircraft within 50 nm of Madrid (40.4168, -3.7038)"
Tool: "📍 Found 23 aircraft within 50 nm of 40.4168, -3.7038: ..."

military_aircraft()

Propósito: Listar todas las aeronaves militares

Entrada: Ninguna

Devuelve: Todas las aeronaves etiquetadas como militares

Ejemplo:

User: "What military aircraft are flying?"
Tool: "🎖️ Found 12 military aircraft: ..."

ladd_aircraft()

Propósito: Listar aeronaves de aplicación de la ley y seguridad

Entrada: Ninguna

Devuelve: Todas las aeronaves LADD (Aplicación de la Ley/Seguridad)

Ejemplo:

User: "Show law enforcement aircraft"
Tool: "🚁 Found 8 LADD aircraft: ..."

pia_aircraft()

Propósito: Listar aeronaves interesantes/especiales

Entrada: Ninguna

Devuelve: Todas las aeronaves PIA (interés especial)

Ejemplo:

User: "Show special/private aircraft"
Tool: "🛡️ Found 156 PIA aircraft: ..."

Formato de Salida

Todas las herramientas devuelven cadenas formateadas con indicadores emoji:

✈️ Callsign: BA387
📋 Registration: G-EUPA
🛩️ Type: A350
📍 Position: 51.4769, -0.4589
📏 Altitude: 35000 ft
⚡ Ground Speed: 485 knots
🧭 Track: 089°
🔖 Mode S Hex: 406ee9
👁️ Last Seen: 3 seconds ago

Esto proporciona:

  • Claridad visual con emojis
  • Escaneo fácil de la información
  • Formato consistente
  • Apariencia profesional

Agregar Nuevas Herramientas

Para agregar una nueva herramienta a este servidor:

Paso 1: Crear la Función de la Herramienta

@mcp.tool()
async def new_tool(param1: str = "", param2: str = "") -> str:
    """Single-line description of what this tool does."""
    if not param1.strip():
        return "❌ Error: param1 is required"
    
    try:
        # Your implementation
        result = await make_api_request("/endpoint")
        formatted = format_aircraft_data(result.get('ac', []))
        return f"✅ Success:\n\n{formatted}"
    except Exception as e:
        return f"❌ Error: {str(e)}"

Paso 2: Agregar al Catálogo

Actualiza la sección tools: en custom.yaml:

tools:
  - name: new_tool

Paso 3: Reconstruir la Imagen Docker

docker build -t airplane-mcp-server .

Paso 4: Reiniciar Claude Desktop

La nueva herramienta aparecerá automáticamente.

Pruebas

Patrón de Pruebas Unitarias

import asyncio

async def test_aircraft_by_callsign():
    result = await aircraft_by_callsign("BA387")
    assert "✈️" in result
    assert "Found" in result
    print(result)

# Run with: asyncio.run(test_aircraft_by_callsign())

Prueba de Integración

# Start server
python airplane_server.py

# In another terminal, test via stdin:
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python airplane_server.py

Consideraciones de Rendimiento

Tiempos de Respuesta de la API

  • Típico: 500ms - 1s
  • Consultas complejas: 1s - 2s
  • Tiempo de espera: 15 segundos

Límites de Datos

  • Máximo 1000 aeronaves por consulta (límite de la API)
  • Búsqueda por radio: máximo 250 millas náuticas
  • Indicativo/matrícula: separados por comas hasta 8000 caracteres

Consejos de Optimización

  1. Usa búsquedas específicas - Las búsquedas estrechas son más rápidas
  2. Evita saturar la API - Frecuencia de solicitudes razonable
  3. Almacena resultados en caché localmente - Considera guardar consultas recientes
  4. Monitorea los tiempos de espera - La API puede ser lenta durante horas pico

Guía de Solución de Problemas

Problema: Las Herramientas No Aparecen

Solución:

  1. Verifica que la imagen esté construida: docker images | grep airplane
  2. Revisa el catálogo: cat ~/.docker/mcp/catalogs/custom.yaml
  3. Verifica el registro: cat ~/.docker/mcp/registry.yaml
  4. Reinicia Claude: Sal completamente y vuelve a abrir

Problema: "No Aircraft Found"

Causas:

  • Coordenadas incorrectas (verifica el formato de lat/lon)
  • Radio demasiado pequeño
  • Sin tráfico en esa área
  • Código de tipo incorrecto (prueba con mayúsculas)

Solución: Prueba con una búsqueda más amplia o diferentes parámetros

Problema: Tiempo de Espera de la API

Causa: La API es lenta o tiene límite de velocidad

Solución:

  • Espera 30 segundos
  • Prueba con una consulta más simple
  • Verifica la conexión a Internet

Problema: Permiso Denegado en Docker

Solución:

# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in
newgrp docker

🗺️ Mejoras Futuras

⚠️ Nota Importante: Este panel planificado está destinado como un complemento educativo al excelente visor global oficial de airplanes.live, no un reemplazo. El objetivo es demostrar la integración del desarrollo web con servidores MCP con fines de aprendizaje.

  • Sistema de Caché - Caché Redis para reducir llamadas a la API
  • Límite de Velocidad - Limitación inteligente de solicitudes
  • Funciones de Exportación - Guardar resultados como JSON/CSV/KML
  • Formato Mejorado - Mejor visualización de datos en Claude
  • Alertas de Vuelo - Notificar cuando aparezcan aeronaves específicas
  • Rastreo Histórico - Almacenar y rastrear movimientos de aeronaves
  • Panel de Estadísticas - Agregar datos y análisis
  • Extensiones de API - Puntos finales adicionales de airplanes.live

🤖 Funciones Impulsadas por IA

  • 🧠 Predicción de Vuelos - Estimación de trayectorias de vuelo basada en ML
  • 📈 Análisis de Patrones - Identifica patrones de vuelo inusuales
  • 🚨 Detección de Anomalías - Alertas automáticas para eventos interesantes
  • 📊 Análisis de Tendencias - Información histórica de datos

Seguridad

Enfoque Actual

  • No se requiere autenticación (datos públicos de la API)
  • Considere solicitar una clave de API para uso en producción
  • No se almacenan credenciales sensibles
  • Se ejecuta como usuario no root
  • Validación de entrada en todos los parámetros

Consideraciones Futuras

  • Agregar limitación de velocidad si es necesario
  • Implementar registro de consultas para monitoreo
  • Considerar almacenamiento en caché para reducir llamadas a la API
  • Agregar saneamiento de entrada para endpoints personalizados

📚 Recursos

🤝 Contribuciones

¡Este es un proyecto educativo de código abierto! Las contribuciones son bienvenidas:

  • 🐛 Informes de errores - Abra un issue
  • 💡 Solicitudes de funciones - Sugiera mejoras
  • 🔧 Pull Requests - Envíe cambios de código
  • 📖 Documentación - Mejore guías y ejemplos

📄 Licencia y Aviso Legal

Licencia MIT - Siéntase libre de usar, modificar y distribuir con fines educativos.

⚖️ Aviso Legal:

  • Este software se proporciona "TAL CUAL" sin garantía
  • El autor no asume responsabilidad por el uso o cumplimiento
  • Los usuarios deben respetar los términos de la API de airplanes.live
  • Solo para uso educativo y no comercial
  • No afiliado con airplanes.live

🎯 Intención del Proyecto:

Este proyecto es una contribución comunitaria con fines educativos, que demuestra el desarrollo de servidores MCP y la integración de APIs. El objetivo es ayudar a los desarrolladores a aprender y contribuir al ecosistema MCP, no con fines comerciales.

Hecho con ❤️ para la comunidad MCP ✈️

¡Recuerde: Siempre respete los términos de la API y úsela de manera responsable!