Airplane.Live MCP Server

Servidor MCP que se conecta à API do Airplanes.live para fornecer dados em tempo real de voos e aeronaves para análise ou visualização.

GitHub

Experimente este MCPPatrocinado

Documentação

✈️ Servidor MCP de Rastreamento de Aeronaves

🎯 Visão Geral

Este servidor MCP integra-se com a API airplanes.live para fornecer capacidades de rastreamento de aeronaves em tempo real para o Claude Desktop. Rastreie voos, encontre aeronaves por indicativo, registro ou posição - tudo diretamente do Claude!

⚠️ Aviso Importante - Termos de Uso

📖 Apenas para Uso Educacional e Não Comercial

Este projeto utiliza a API airplanes.live que é fornecida apenas para fins educacionais e não comerciais. Por favor, respeite seus termos de serviço.

📋 Diretrizes de Uso:

✅ Projetos educacionais - Aprendizado e pesquisa

✅ Uso pessoal - Rastreamento não comercial

✅ Contribuições de código aberto - Desenvolvimento comunitário

❌ Aplicações comerciais - Fins comerciais/lucrativos

❌ Requisições em alto volume - Respeite os limites de taxa

🛡️ Aviso Legal:

O autor deste servidor MCP não assume qualquer responsabilidade pelo uso deste software. Esta é uma contribuição comunitária destinada a fins educacionais e para demonstrar o desenvolvimento de servidores MCP. Os usuários são responsáveis por cumprir os termos da API airplanes.live e quaisquer regulamentações aplicáveis.

🌐 Respeito pelos Serviços Existentes:

Este projeto NÃO pretende substituir ou competir com o visualizador globe oficial do airplanes.live. O globe oficial é a forma primária e recomendada de visualizar dados de voo. Este servidor MCP foi projetado como uma ferramenta educacional complementar para integração com Claude Desktop e aprendizado de desenvolvimento MCP.

📖 Termos Completos da API: https://airplanes.live/api-guide/
🌍 Visualizador Globe Oficial: https://globe.airplanes.live

📸 Capturas de Tela

Claude Desktop with Airplane Tracker Rastreamento de aeronaves em tempo real no Claude Desktop

🚀 Recursos

🔍 Busca por Indicativo - Encontre voos específicos (ex.: UAL123)
📋 Consulta por Registro - Rastreie pelo número de cauda (ex.: N12345)
🎯 Busca por Posição - Aeronaves próximas a coordenadas
🏷️ Busca por ID Hex - Códigos de transponder Mode S
🛡️ Aeronaves Militares - Voos militares rastreados
🚁 Aeronaves LADD - Rastreamento de aplicação da lei
⭐ Aeronaves PIA - Aeronaves privadas/interessantes
📡 Códigos Squawk - Códigos de emergência e especiais

Exemplos variados de busca na API

🏗️ Arquitetura

🔧 Componentes

🐍 Servidor MCP em Python - Implementação de servidor assíncrono
🌐 Framework MCP - Arquitetura moderna de servidor
⚡ Cliente httpx - Requisições HTTP de alto desempenho
📊 Formatador de Dados - Informações de aeronaves limpas e legíveis
🔌 Integração Claude - Suporte direto ao protocolo MCP

📊 Fluxo de Dados

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

Arquitetura do sistema e fluxo de dados

🚀 Início Rápido

📋 Pré-requisitos

🐍 Python 3.8+
💻 Claude Desktop
🌐 Conexão com a internet

⚡ Instalação

# 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 Comuns e Soluções

🔥 Ambiente Virtual é OBRIGATÓRIO!

Se você pular os passos 2-3, receberá ModuleNotFoundError: No module named 'httpx'
O Claude Desktop precisa do caminho completo para o Python do venv, não o Python do sistema
Sem venv, as dependências não são isoladas e as coisas quebram

🪟 Usuários Windows:

O ambiente virtual cria a pasta .venv\Scripts\ (não .venv\bin\)
Use Scripts\python.exe na configuração do Claude, não bin/python
Sempre use barras invertidas duplas \\ em caminhos JSON

🐍 Problemas com Caminho do Python:

Certifique-se de que o Python 3.8+ está instalado: python --version
Se python não funcionar, tente python3 ou py
O ambiente virtual DEVE existir antes de configurar o Claude Desktop

🐳 Instalação com Docker (Alternativa)

Evite os problemas de configuração do Python - use Docker!

📋 Pré-requisitos

🐳 Docker Desktop instalado e em execução
💻 Claude Desktop

⚡ Configuração do 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

⚙️ Configuração do Claude Desktop para Docker

🍎 macOS/Linux com Docker

Adicione 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 com Docker

Adicione a %APPDATA%\Claude\claude_desktop_config.json:

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

🔄 Referência de Comandos 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>

✅ Vantagens do Docker

🚀 Sem necessidade de configuração Python - Tudo pré-configurado
🔒 Ambiente isolado - Sem conflitos de dependências
🌍 Funciona em qualquer lugar - Mesma configuração no Windows/Mac/Linux
📦 Atualizações fáceis - Basta reconstruir a imagem
🛡️ Comportamento consistente - Elimina o problema "funciona na minha máquina"

⚠️ Solução de Problemas do 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: Falha na construção da imagem

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

🎯 Ainda Mais Fácil: Docker Compose

Para a configuração mais simples, use 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

Configuração do Claude com 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"
    }
  }
}

🐳 Como Usar com o Claude Desktop

Método 1: Docker Run Simples

Configuração para todas as plataformas:

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

Método 2: Docker Compose (Avançado)

Configuração com caminhos completos:

{
  "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"
    }
  }
}

Passos Completos da Configuração 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"

🎯 Comparação Docker vs Python:

Método	Prós	Contras	Melhor Para
Docker	✅ Sem configuração Python ✅ Funciona em qualquer lugar ✅ Isolado	❌ Requer Docker ❌ Leve overhead	Iniciantes, usuários Windows
Python	✅ Execução direta ✅ Depuração fácil ✅ Sem necessidade de Docker	❌ Configuração manual do Python ❌ Problemas específicos de SO	Desenvolvedores, usuários experientes

Comandos 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"
      }
    }
  }
}

🪟 Configuração Windows

Adicione 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:

Use Scripts\\python.exe (não bin/python)
Substitua YourUsername pelo seu nome de usuário real do Windows
Use barras invertidas duplas \\ nos caminhos
Certifique-se de que o ambiente virtual foi criado com python -m venv .venv

Configuração do Claude Desktop

🎮 Exemplos de Uso

Busca por Indicativo

🔍 Find flight UAL123

Busca por Posição Próxima

📍 Show aircraft near 40.7128, -74.0060 within 50nm

Aeronaves Militares

🛡️ Show all military aircraft

🔧 Principais Decisões de Design

1. Implementação Assíncrona

Todas as ferramentas usam async para lidar com múltiplas requisições de forma eficiente:

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

Isso permite que o servidor processe requisições concorrentes sem bloqueio.

2. Parâmetros Baseados em String

Todos os parâmetros são strings porque os protocolos MCP funcionam melhor com tipos simples:

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

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

3. Tratamento de Erros

Cada ferramenta inclui tratamento abrangente de erros:

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

4. Formatação de Dados

A função format_aircraft_data() fornece saída consistente e legível:

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

5. Wrapper da API

A função make_api_request() centraliza a 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()

Esta abordagem:

Centraliza o tratamento de erros
Gerencia timeouts
Registra todas as requisições
Facilita a adição de autenticação posteriormente

Referência de Ferramentas

aircraft_by_hex(hex_id: str = "")

Propósito: Buscar aeronaves pelo identificador hex Mode S

Entrada: IDs hex separados por vírgula (ex.: "45211e,45212f")

Retorno: Lista de aeronaves correspondentes com detalhes completos

Exemplo:

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

aircraft_by_callsign(callsign: str = "")

Propósito: Buscar aeronaves pelo indicativo de voo

Entrada: Indicativos separados por vírgula (ex.: "BA387,AA123")

Retorno: Aeronaves correspondentes ao indicativo

Exemplo:

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

aircraft_by_registration(reg: str = "")

Propósito: Buscar aeronaves pelo número de cauda/registro

Entrada: Registros separados por vírgula (ex.: "N123AB,G-EUPA")

Retorno: Aeronaves correspondentes ao registro

Exemplo:

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

aircraft_by_type(icao_type: str = "")

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

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

Retorno: Todas as aeronaves desse tipo atualmente em voo

Exemplo:

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

aircraft_by_squawk(squawk_code: str = "")

Propósito: Buscar aeronaves pelo código squawk

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

Retorno: Aeronaves transmitindo esse código

Nota: 7700 = Emergência, 7600 = Falha de comunicação, 7500 = Sequestro

Exemplo:

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

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

Propósito: Encontrar todas as aeronaves dentro de um raio de coordenadas

Entrada:

latitude (graus decimais, -90 a 90)
longitude (graus decimais, -180 a 180)
raio (milhas náuticas, máximo 250)

Retorno: Todas as aeronaves dentro do raio

Exemplo:

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 as aeronaves militares

Entrada: Nenhuma

Retorno: Todas as aeronaves marcadas como militares

Exemplo:

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

ladd_aircraft()

Propósito: Listar aeronaves de aplicação da lei e segurança

Entrada: Nenhuma

Retorno: Todas as aeronaves LADD (Aplicação da Lei/Segurança)

Exemplo:

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

pia_aircraft()

Propósito: Listar aeronaves interessantes/especiais

Entrada: Nenhuma

Retorno: Todas as aeronaves PIA (interesse especial)

Exemplo:

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

Formato de Saída

Todas as ferramentas retornam strings formatadas com 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

Isso fornece:

Clareza visual com emojis
Leitura fácil das informações
Formatação consistente
Aparência profissional

Adicionando Novas Ferramentas

Para adicionar uma nova ferramenta a este servidor:

Passo 1: Crie a Função da Ferramenta

@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)}"

Passo 2: Adicione ao Catálogo

Atualize a seção tools: no custom.yaml:

tools:
  - name: new_tool

Passo 3: Reconstrua a Imagem Docker

docker build -t airplane-mcp-server .

Passo 4: Reinicie o Claude Desktop

A nova ferramenta aparecerá automaticamente.

Testes

Padrão de Teste Unitário

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())

Teste de Integração

# 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

Considerações de Desempenho

Tempos de Resposta da API

Típico: 500ms - 1s
Consultas complexas: 1s - 2s
Timeout: 15 segundos

Limites de Dados

Máximo de 1000 aeronaves por consulta (limite da API)
Busca por raio: máximo de 250 milhas náuticas
Indicativo/registro: separados por vírgula até 8000 caracteres

Dicas de Otimização

Use buscas específicas - Buscas restritas são mais rápidas
Evite sobrecarregar a API - Frequência razoável de requisições
Armazene resultados em cache localmente - Considere guardar consultas recentes
Monitore timeouts - A API pode ficar lenta durante picos de tráfego

Guia de Solução de Problemas

Problema: Ferramentas Não Aparecem

Solução:

Verifique se a imagem foi construída: docker images | grep airplane
Verifique o catálogo: cat ~/.docker/mcp/catalogs/custom.yaml
Verifique o registro: cat ~/.docker/mcp/registry.yaml
Reinicie o Claude: Saia completamente e reabra

Problema: "Nenhuma Aeronave Encontrada"

Causas:

Coordenadas erradas (verifique o formato lat/lon)
Raio muito pequeno
Sem tráfego na área
Código de tipo errado (tente maiúsculas)

Solução: Tente uma busca mais ampla ou parâmetros diferentes

Problema: Timeout da API

Causa: A API está lenta ou com limite de taxa atingido

Solução:

Aguarde 30 segundos
Tente uma consulta mais simples
Verifique a conexão com a internet

Problema: Permissão Negada no Docker

Solução:

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

🗺️ Melhorias Futuras

⚠️ Nota Importante: Este painel planejado é destinado como um complemento educacional ao excelente visualizador globe oficial do airplanes.live, não um substituto. O objetivo é demonstrar a integração de desenvolvimento web com servidores MCP para fins de aprendizado.

Sistema de Cache - Cache Redis para reduzir chamadas à API
Limite de Taxa - Limitação inteligente de requisições
Recursos de Exportação - Salvar resultados como JSON/CSV/KML
Formatação Aprimorada - Melhor visualização de dados no Claude
Alertas de Voo - Notificar quando aeronaves específicas aparecerem
Rastreamento Histórico - Armazenar e rastrear movimentos de aeronaves
Painel de Estatísticas - Agregar dados e análises
Extensões da API - Endpoints adicionais do airplanes.live

🤖 Recursos com IA

🧠 Previsão de Voos - Estimativa de trajetória de voo baseada em ML
📈 Análise de Padrões - Identifique padrões de voo incomuns
🚨 Detecção de Anomalias - Alertas automatizados para eventos interessantes
📊 Análise de Tendências - Insights de dados históricos

Segurança

Abordagem Atual

Nenhuma autenticação necessária (dados públicos da API)
Considere solicitar uma chave de API para uso em produção
Nenhuma credencial sensível armazenada
Executa como usuário não root
Validação de entrada em todos os parâmetros

Considerações Futuras

Adicionar limite de taxa, se necessário
Implementar registro de consultas para monitoramento
Considerar cache para reduzir chamadas de API
Adicionar sanitização de entrada para endpoints personalizados

📚 Recursos

Documentação da API: https://airplanes.live/
Termos de Uso da API: https://airplanes.live/api-guide/
Especificação MCP: https://docs.anthropic.com/mcp
Documentação do FastMCP: https://github.com/jlowin/fastmcp
Documentação do httpx: https://www.python-httpx.org/

🤝 Contribuindo

Este é um projeto educacional de código aberto! Contribuições são bem-vindas:

🐛 Relatórios de Bugs - Abra uma issue
💡 Solicitações de Recursos - Sugira melhorias
🔧 Pull Requests - Envie alterações de código
📖 Documentação - Melhore guias e exemplos

📄 Licença e Aviso Legal

Licença MIT - Sinta-se à vontade para usar, modificar e distribuir para fins educacionais.

⚖️ Aviso Legal:

Este software é fornecido "NO ESTADO EM QUE SE ENCONTRA", sem garantia
O autor não assume responsabilidade pelo uso ou conformidade
Os usuários devem respeitar os termos da API do airplanes.live
Uso educacional e não comercial apenas
Não afiliado ao airplanes.live

🎯 Intenção do Projeto:

Este projeto é uma contribuição da comunidade para fins educacionais, demonstrando o desenvolvimento de servidores MCP e integração de APIs. O objetivo é ajudar desenvolvedores a aprender e contribuir com o ecossistema MCP, não para ganho comercial.

Feito com ❤️ para a comunidade MCP ✈️

Lembre-se: Sempre respeite os termos da API e use com responsabilidade!