Flight Search

Pesquise voos usando o mecanismo SerpAPI Google Flights.

GitHub
2
Experimente este MCPPatrocinado

Documentação

Flight Search MCP Server

Um servidor confiável de Model Context Protocol (MCP) para buscar voos usando o mecanismo Google Flights da SerpAPI. Este servidor oferece recursos de busca de voos em tempo real para voos de ida e volta. Funciona bem com claude ai desktop

✈️ Recursos

  • Busca de voos em tempo real usando o Google Flights da SerpAPI
  • Suporte a voos de ida e ida e volta
  • Múltiplas opções de voo com preços, horários e detalhes das companhias aéreas
  • Implementação do protocolo MCP compatível com JSON-RPC 2.0
  • Integração fácil com o Claude e outros clientes MCP
  • Tratamento robusto de erros e registro de logs

🚀 Início Rápido

Pré-requisitos

  • Python 3.7 ou superior
  • Conta e chave de API da SerpAPI (Obtenha uma aqui)
  • Cliente compatível com MCP (Claude, etc.)

Instalação

  1. Clone ou baixe o arquivo do servidor:
mkdir -p ~/tools/flightsearch
# Copy flight_search_server.py to ~/tools/flightsearch/
  1. Instale as dependências:
pip install requests
  1. Obtenha sua chave da SerpAPI:
    • Cadastre-se na SerpAPI
    • Obtenha sua chave de API no painel de controle

Configuração

Adicione o seguinte à configuração do seu cliente MCP:

{
  "flightsearch": {
    "command": "python3",
    "args": [
      "/path/to/your/tools/flightsearch/flight_search_server.py",
      "--connection_type", 
      "stdio"
    ],
    "env": {
      "SERP_API_KEY": "your_serpapi_key_here"
    }
  }
}

Para o Claude Desktop, adicione isto ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "flightsearch": {
      "command": "python3",
      "args": [
        "/Users/yourusername/tools/flightsearch/flight_search_server.py",
        "--connection_type", 
        "stdio"
      ],
      "env": {
        "SERP_API_KEY": "your_serpapi_key_here"
      }
    }
  }
}

📖 Uso

Ferramentas Disponíveis

search_flights

Busque voos entre aeroportos.

Parâmetros:

  • origin (obrigatório): Código do aeroporto de origem (ex.: "JFK", "LAX")
  • destination (obrigatório): Código do aeroporto de destino (ex.: "JFK", "LAX")
  • outbound_date (obrigatório): Data de partida no formato YYYY-MM-DD
  • return_date (opcional): Data de retorno para voos de ida e volta no formato YYYY-MM-DD

Exemplos:

# One-way flight
search_flights(origin="JFK", destination="LAX", outbound_date="2025-07-01")

# Round-trip flight  
search_flights(origin="JFK", destination="LAX", outbound_date="2025-07-01", return_date="2025-07-08")

server_status

Verifique se o servidor de busca de voos está em execução.

Parâmetros: Nenhum

Exemplo de Resposta

{
  "status": "success",
  "origin": "JFK",
  "destination": "LAX", 
  "outbound_date": "2025-07-01",
  "return_date": null,
  "trip_type": "one_way",
  "flights": [
    {
      "price": 199,
      "departure_time": "2025-07-01 08:40",
      "arrival_time": "2025-07-01 11:45", 
      "airline": "Delta",
      "duration": 365,
      "stops": 0
    },
    {
      "price": 204,
      "departure_time": "2025-07-01 09:00",
      "arrival_time": "2025-07-01 12:00",
      "airline": "JetBlue", 
      "duration": 360,
      "stops": 0
    }
  ]
}

🔧 Desenvolvimento

Executando Testes

Teste o servidor diretamente:

# Set environment variable
export SERP_API_KEY="your_api_key"

# Run the server  
python3 flight_search_server.py --connection_type stdio

Teste de Protocolo

O servidor implementa JSON-RPC 2.0 e suporta os seguintes métodos:

  • initialize - Inicializa a conexão MCP
  • tools/list - Lista as ferramentas disponíveis
  • tools/call - Executa uma ferramenta
  • ping - Verificação de integridade
  • notifications/initialized - Notificação de inicialização

Registro de Logs

O servidor registra logs em stderr para depuração:

# View logs while running
python3 flight_search_server.py --connection_type stdio 2>debug.log

🐛 Solução de Problemas

Problemas Comuns

1. "API request failed: 400 Client Error"

  • Verifique se sua chave da SerpAPI é válida
  • Confirme se os códigos de aeroporto estão corretos (use códigos IATA como "JFK", "LAX")
  • Garanta que o formato da data seja YYYY-MM-DD

2. "SERP_API_KEY environment variable not set"

  • Certifique-se de que a chave de API está configurada corretamente na sua configuração MCP
  • Verifique se o nome da variável de ambiente é exatamente SERP_API_KEY

3. "JSON-RPC schema validation errors"

  • Reinicie seu cliente MCP para recarregar o servidor
  • Confirme se você está usando a versão mais recente do servidor

4. Nenhum voo encontrado

  • Tente códigos de aeroporto ou datas diferentes
  • Algumas rotas podem não estar disponíveis para a data selecionada
  • Verifique a documentação da SerpAPI para aeroportos suportados

Modo de Depuração

Ative o registro de logs de depuração:

# Add to the top of flight_search_server.py
logging.basicConfig(level=logging.DEBUG, stream=sys.stderr)

📝 Limitações da API

  • Limites de taxa da SerpAPI: Verifique seu plano da SerpAPI para limites de requisições
  • Dados de voos: Os resultados dependem da disponibilidade de dados do Google Flights
  • Intervalo de datas: Somente datas futuras (não é possível buscar voos passados)
  • Códigos de aeroporto: Deve usar códigos IATA de aeroporto válidos

🤝 Contribuição

  1. Faça um fork do repositório
  2. Crie uma branch de funcionalidade
  3. Faça suas alterações
  4. Adicione testes se aplicável
  5. Envie um pull request

Configuração de Desenvolvimento

# Clone the repo
git clone https://github.com/yourusername/flight-search-mcp.git
cd flight-search-mcp

# Install dependencies
pip install requests

# Run tests
python3 test_mcp_protocol.py
python3 test_flight_search.py

📄 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

  • SerpAPI por fornecer a API do Google Flights
  • Anthropic pela especificação do protocolo MCP
  • A comunidade de código aberto por inspiração e feedback

📞 Suporte

Feito com ❤️ para a comunidade MCP