Aviationstack

Um servidor MCP que utiliza a API AviationStack para obter dados de voos em tempo real, incluindo voos de companhias aéreas, horários de aeroportos, voos futuros e tipos de aeronaves.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP Aviationstack

Este projeto é um servidor MCP (Model Context Protocol) que fornece um conjunto de ferramentas para interagir com a API AviationStack. Ele expõe endpoints para recuperar dados de voos em tempo real e futuros, detalhes de aeronaves e aviões, e dados de referência essenciais (aeroportos, companhias aéreas, rotas, impostos), facilitando a integração de dados de aviação em suas aplicações.

Você também pode encontrar o servidor MCP Aviationstack nestes repositórios conhecidos de servidores MCP para fácil acesso:

Demonstração

https://github.com/user-attachments/assets/9325fcce-8ecc-4b01-8923-4ccb2f6968f4

Recursos

Consultar um único voo pelo seu número de voo
Obter voos para uma companhia aérea específica
Buscar voos históricos por data
Recuperar horários de chegada e partida para aeroportos
Buscar horários de voos futuros (de amanhã até cerca de 12 meses à frente)
Obter tipos de aeronaves aleatórios
Obter informações detalhadas sobre aviões aleatórios
Obter informações detalhadas sobre países aleatórios
Obter informações detalhadas sobre cidades aleatórias
Listar aeroportos, companhias aéreas, rotas e impostos

Todos os endpoints são implementados como ferramentas MCP e estão prontos para uso em um ambiente compatível com MCP.

Cada ferramenta retorna o mesmo envelope JSON. Em caso de sucesso: {"ok": true, "count": N, "data": [...]}, além de um bloco pagination nas ferramentas list_* e um message quando não houver correspondências. Em caso de falha: {"ok": false, "context": "...", "error": "..."}. Qualquer limit é limitado a 100 registros por chamada.

Pré-requisitos

Chave da API Aviationstack (Você pode obter uma chave de API GRATUITA em Aviationstack)
Python 3.13 ou mais recente
Gerenciador de pacotes uv instalado

Ferramentas Disponíveis

Ferramenta	Descrição	Parâmetros
`get_flight_status(flight_iata: str, flight_date: str = "")`	Consultar um voo pelo seu número de voo IATA, para hoje ou uma data específica.	- `flight_iata`: Número IATA do voo (ex.: "AA100") - `flight_date`: Data opcional no formato `YYYY-MM-DD`
`flights_with_airline(airline_name: str, number_of_flights: int, flight_status: str = "")`	Obter voos ao vivo para uma companhia aérea específica.	- `airline_name`: Nome da companhia aérea (ex.: "Delta Air Lines") - `number_of_flights`: Número de voos a retornar - `flight_status`: Filtro de status opcional: `scheduled`, `active`, `landed`, `cancelled`, `incident`, `diverted`
`historical_flights_by_date(flight_date: str, number_of_flights: int, airline_iata: str = "", dep_iata: str = "", arr_iata: str = "")`	Obter voos históricos para uma data (plano Basic+).	- `flight_date`: Data no formato `YYYY-MM-DD` - `number_of_flights`: Número de voos a retornar - `airline_iata`: Filtro IATA de companhia aérea opcional - `dep_iata`: Filtro IATA de aeroporto de partida opcional - `arr_iata`: Filtro IATA de aeroporto de chegada opcional
`flight_arrival_departure_schedule(airport_iata_code: str, schedule_type: str, airline_name: str, number_of_flights: int)`	Obter o quadro de chegadas ou partidas de hoje para um aeroporto e companhia aérea específicos. Apenas o dia atual.	- `airport_iata_code`: Código IATA do aeroporto (ex.: "JFK") - `schedule_type`: "arrival" ou "departure" - `airline_name`: Nome da companhia aérea - `number_of_flights`: Número de voos a retornar
`future_flights_arrival_departure_schedule(airport_iata_code: str, schedule_type: str, airline_iata: str, date: str, number_of_flights: int)`	Obter voos programados para um aeroporto, companhia aérea e data futura específicos. Abrange de amanhã até cerca de 12 meses à frente, incluindo os próximos 7 dias.	- `airport_iata_code` : Código IATA do aeroporto - `schedule_type`: "arrival" ou "departure" - `airline_iata`: Código IATA da companhia aérea (ex.: "DL" para Delta) - `date`: Data no formato `YYYY-MM-DD`, de amanhã até cerca de 12 meses à frente - `number_of_flights`: Número de voos a retornar
`random_aircraft_type(number_of_aircraft: int)`	Obter tipos de aeronaves a partir de um deslocamento aleatório no conjunto de dados.	- `number_of_aircraft`: Número de tipos de aeronaves a retornar
`random_airplanes_detailed_info(number_of_airplanes: int)`	Obter informações detalhadas sobre aviões a partir de um deslocamento aleatório no conjunto de dados.	- `number_of_airplanes`: Número de aviões a retornar
`random_countries_detailed_info(number_of_countries: int)`	Obter informações detalhadas sobre países a partir de um deslocamento aleatório no conjunto de dados.	- `number_of_countries`: Número de países a retornar
`random_cities_detailed_info(number_of_cities: int)`	Obter informações detalhadas sobre cidades a partir de um deslocamento aleatório no conjunto de dados.	- `number_of_cities`: Número de cidades a retornar
`list_airports(limit: int = 10, offset: int = 0, search: str = "")`	Listar aeroportos.	- `limit`: Número de resultados a retornar - `offset`: Deslocamento de paginação - `search`: Consulta de busca opcional
`list_airlines(limit: int = 10, offset: int = 0, search: str = "")`	Listar companhias aéreas.	- `limit`: Número de resultados a retornar - `offset`: Deslocamento de paginação - `search`: Consulta de busca opcional
`list_routes(limit: int = 10, offset: int = 0, airline_iata: str = "", dep_iata: str = "", arr_iata: str = "")`	Listar rotas.	- `limit`: Número de resultados a retornar - `offset`: Deslocamento de paginação - `airline_iata`: Filtro IATA de companhia aérea opcional - `dep_iata`: Filtro IATA de aeroporto de partida opcional - `arr_iata`: Filtro IATA de aeroporto de chegada opcional
`list_taxes(limit: int = 10, offset: int = 0, search: str = "")`	Listar impostos de aviação.	- `limit`: Número de resultados a retornar - `offset`: Deslocamento de paginação - `search`: Consulta de busca opcional

Prompts

O servidor inclui prompts reutilizáveis que orientam um modelo para a ferramenta correta.

Prompt	Argumentos	Propósito
`plan_flight_status_lookup`	`flight_iata`, `flight_date`	Verificar um voo específico e explicar seus códigos compartilhados.
`plan_airline_flight_lookup`	`airline_name`, `number_of_flights`	Consultar voos ao vivo para uma companhia aérea.
`plan_future_schedule_lookup`	`airport_iata_code`, `date`, `schedule_type`	Consultar um horário futuro de aeroporto.
`plan_reference_data_lookup`	`data_type`, `search`	Explorar dados de referência de aeroporto, companhia aérea, rota ou imposto.

Recursos

Recurso	URI	Conteúdo
`server_metadata`	`aviationstack://meta/server`	URL base da API e as variáveis de chave de API aceitas.
`aviationstack_endpoints`	`aviationstack://meta/endpoints`	Os endpoints da Aviationstack que cada ferramenta chama.
`tool_input_examples`	`aviationstack://examples/tool-input/{tool_name}`	Um payload de exemplo para uma determinada ferramenta.

Desenvolvimento

A lógica principal do servidor está em src/aviationstack_mcp/server.py.
Todas as ferramentas MCP são definidas como funções Python decoradas com @mcp.tool().
Cada ferramenta é um wrapper fino que valida a entrada com um modelo Pydantic e depois chama a função simples correspondente. Os testes visam as funções simples.
O servidor usa a classe FastMCP de mcp.server.fastmcp. A dependência mcp é fixada em <2, porque a versão 2.x renomeia FastMCP para MCPServer.
As ferramentas nunca lançam exceções. Toda falha é capturada e retornada como envelope de erro.

Configure e execute as verificações que o CI executa:

uv sync --all-groups

# Unit tests
uv run python -m unittest discover -s tests -v

# Lint, must stay at 10.00/10
uv run pylint $(git ls-files '*.py')

# Coverage
uv run coverage run --source=aviationstack_mcp -m unittest discover -s tests
uv run coverage report

.well-known/mcp/server-card.json é gerado, não editado manualmente. Após alterar qualquer ferramenta, prompt ou recurso, regenere-o ou o CI falhará:

uv run python scripts/generate_server_card.py          # rewrite the card
uv run python scripts/generate_server_card.py --check  # what CI runs

Configuração do servidor MCP

Para adicionar este servidor ao seu cliente MCP favorito, você pode adicionar o seguinte ao arquivo de configuração do seu cliente MCP.

Usando uvx sem clonar o repositório (recomendado)

{
  "mcpServers": {
    "Aviationstack MCP": {
      "command": "uvx",
      "args": [
        "aviationstack-mcp"
      ],
      "env": {
        "AVIATION_STACK_API_KEY": "<your-api-key>"
      }
    }
  }
}

Clonando o repositório e executando o servidor localmente

{
  "mcpServers": {
    "Aviationstack MCP": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/aviationstack-mcp/src/aviationstack_mcp",
        "run",
        "-m",
        "aviationstack_mcp",
        "mcp",
        "run"
      ],
      "env": {
        "AVIATION_STACK_API_KEY": "<your-api-key>"
      }
    }
  }
}

Licença

Este projeto é licenciado sob a Licença MIT. Consulte LICENSE para obter detalhes.