SearchAPI

Fornece acesso padronizado ao Google Maps, Google Flights, Google Hotels e outros serviços via SearchAPI.

GitHub
74
Experimente este MCPPatrocinado

Documentação

Servidor MCP SearchAPI

License: MIT Python 3.10+ FastMCP

Um servidor Model Context Protocol (MCP) pronto para produção que fornece recursos abrangentes de busca através da SearchAPI.io. Permite que assistentes de IA pesquisem no Google, Mapas, Voos, Hotéis e muito mais, com cache integrado, lógica de repetição e disjuntores.

Recursos • Início Rápido • Instalação • Configuração • Ferramentas Disponíveis

Recursos

🔍 Mecanismos de Busca

  • Google Search - Resultados da web, grafo de conhecimento, caixas de resposta, perguntas relacionadas
  • Google Videos - Busca de vídeos com filtros por duração, fonte e data de upload
  • Google AI Mode - Visões gerais geradas por IA com fontes citadas e conteúdo estruturado
  • Google Maps - Locais, empresas, avaliações e detalhes de localização
  • Google Maps Place - Informações detalhadas para locais específicos (horários, fotos, comodidades)
  • Google Events - Encontre shows, conferências, festivais e atividades locais
  • Google Flights - Busca de voos com filtros abrangentes e calendários de preços
  • Google Flights Location Search - Consulta de códigos de aeroporto e autocompletar
  • Google Travel Explore - Descubra destinos e inspiração para viagens
  • Google Hotels - Busca de hospedagem com comodidades, avaliações e filtros de preço

🏗️ Arquitetura Pronta para Produção

  • Pool de Conexões - Gerenciamento eficiente de conexões HTTP com httpx
  • Cache de Respostas - Cache configurável baseado em TTL com política de remoção LRU
  • Lógica de Repetição - Backoff exponencial para falhas transitórias
  • Disjuntor - Padrão à prova de falhas que previne falhas em cascata
  • Coleta de Métricas - Contagem de requisições, latências, taxas de acerto de cache, rastreamento de erros
  • Verificações de Saúde - Monitore a conectividade da API e o status do serviço

⚙️ Configuração e Monitoramento

  • Validação Pydantic - Configuração type-safe com suporte a variáveis de ambiente
  • Registro Estruturado - Níveis de log configuráveis com rastreamento detalhado de requisições
  • Gerenciamento de Recursos - Limpeza automática e desligamento gracioso
  • Variáveis de Ambiente - Configuração flexível para diferentes implantações

Início Rápido

Pré-requisitos

Instalação com UV (Recomendado)

A maneira mais rápida de começar é usando uvx:

# Set your API key
export SEARCHAPI_API_KEY="your_api_key_here"

# Run directly with uvx (no installation needed)
uvx --from git+https://github.com/RmMargt/searchAPI-mcp.git mcp-server-searchapi

Instalação

Método 1: UV (Recomendado)

UV é o método mais rápido e conveniente:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/RmMargt/searchAPI-mcp.git
cd searchAPI-mcp

# Install dependencies
uv pip install -r requirements.txt

Método 2: pip

# Clone the repository
git clone https://github.com/RmMargt/searchAPI-mcp.git
cd searchAPI-mcp

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Método 3: A partir do código-fonte

git clone https://github.com/RmMargt/searchAPI-mcp.git
cd searchAPI-mcp

# Using uv
uv pip install httpx fastmcp python-dotenv pydantic pydantic-settings

# Or using pip
pip install httpx fastmcp python-dotenv pydantic pydantic-settings

Configuração

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

# Required
SEARCHAPI_API_KEY=your_api_key_here

# Optional - API Configuration
SEARCHAPI_API_URL=https://www.searchapi.io/api/v1/search
TIMEOUT=30.0
MAX_RETRIES=3
RETRY_BACKOFF=1.0

# Optional - Cache Configuration
ENABLE_CACHE=true
CACHE_TTL=3600
CACHE_MAX_SIZE=1000

# Optional - Connection Pool
POOL_CONNECTIONS=10
POOL_MAXSIZE=10

# Optional - Monitoring
ENABLE_METRICS=true
LOG_LEVEL=INFO

Configuração do Cliente MCP

Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop:

Localização:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Usando UV (Recomendado):

{
  "mcpServers": {
    "searchapi": {
      "command": "uvx",
      "args": [
        "--directory",
        "/absolute/path/to/searchAPI-mcp",
        "python",
        "mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Usando Python diretamente:

{
  "mcpServers": {
    "searchapi": {
      "command": "python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Usando ambiente virtual:

{
  "mcpServers": {
    "searchapi": {
      "command": "/absolute/path/to/searchAPI-mcp/venv/bin/python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

VS Code (Continue, Cline)

Adicione a .vscode/mcp.json no seu workspace ou use o comando "MCP: Open User Configuration":

{
  "servers": {
    "searchapi": {
      "command": "python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Com UV:

{
  "servers": {
    "searchapi": {
      "command": "uvx",
      "args": [
        "--directory",
        "/absolute/path/to/searchAPI-mcp",
        "python",
        "mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Editor Zed

Adicione a ~/.config/zed/settings.json:

{
  "context_servers": {
    "searchapi": {
      "command": {
        "path": "python",
        "args": [
          "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
        ],
        "env": {
          "SEARCHAPI_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Cline (Extensão do VS Code)

Nas configurações do Cline, adicione aos Servidores MCP:

{
  "mcpServers": {
    "searchapi": {
      "command": "python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cliente MCP Genérico

Para qualquer cliente compatível com MCP:

# Using stdio transport (default)
python /path/to/searchAPI-mcp/mcp_server_refactored.py

# With environment variable
SEARCHAPI_API_KEY=your_key python mcp_server_refactored.py

Ferramentas Disponíveis

Saúde e Monitoramento

health_check

Verifique a saúde e o desempenho do serviço SearchAPI.

Retorna:

  • Status de conectividade da API
  • Latência de resposta
  • Estado do disjuntor
  • Estatísticas de cache
  • Métricas de requisições

Exemplo:

{
  "api_status": {
    "status": "healthy",
    "latency_ms": 145.23,
    "circuit_breaker": "closed"
  },
  "cache_stats": {
    "size": 42,
    "max_size": 1000,
    "ttl": 3600
  },
  "metrics": {
    "request_count": 156,
    "error_count": 2,
    "cache_hit_rate": 0.67
  }
}

Utilitários de Tempo e Data

get_current_time

Obtenha a hora atual e sugestões de datas de viagem. Essencial para reservas de voos e hotéis.

Parâmetros:

  • format - Formato da data: "iso", "slash", "chinese", "timestamp", "full"
  • days_offset - Dias a partir de hoje (pode ser negativo)
  • return_future_dates - Retorna uma matriz de datas futuras
  • future_days - Número de datas futuras (se return_future_dates=true)

Exemplo:

# Get today's date in ISO format
get_current_time(format="iso")
# Returns: {"date": "2025-11-16", "now": {...}, "travel_dates": {...}}

# Get date 7 days from now with future dates array
get_current_time(days_offset=7, return_future_dates=True, future_days=30)

Google Search

search_google

Pesquise no Google por resultados da web, grafos de conhecimento e caixas de resposta.

Parâmetros:

  • q (obrigatório) - Consulta de pesquisa
  • location - Nome do local (ex.: "Nova York, NY")
  • gl - Código do país (padrão: "us")
  • hl - Código do idioma (padrão: "en")
  • time_period - Filtro de tempo: "last_hour", "last_day", "last_week", "last_month", "last_year"
  • num - Resultados por página (padrão: "10")
  • safe - Busca segura: "off", "active"

Exemplo:

search_google(
    q="Python programming tutorials",
    location="San Francisco, CA",
    time_period="last_month",
    num="20"
)

search_google_videos

Pesquise vídeos no Google Videos.

Parâmetros: Semelhantes ao search_google com filtros específicos de vídeo

  • q (obrigatório) - Consulta de pesquisa
  • time_period - Filtrar por data de upload
  • device - "desktop" ou "mobile"

Exemplo:

search_google_videos(
    q="machine learning tutorial",
    time_period="last_week",
    num="10"
)

search_google_ai_mode

Pesquise com visões gerais geradas por IA e fontes citadas.

Parâmetros:

  • q - Consulta de pesquisa (obrigatório, a menos que url seja fornecida)
  • url - URL da imagem para pesquisa
  • location - Local para resultados localizados

Retorna:

  • Visão geral gerada por IA com citações
  • Blocos de conteúdo estruturado (parágrafos, listas, tabelas, código)
  • Links de referência
  • Resultados da web

Exemplo:

search_google_ai_mode(
    q="How does machine learning work?",
    location="United States"
)

Google Maps

search_google_maps

Pesquise por locais, empresas e serviços.

Parâmetros:

  • query (obrigatório) - Consulta de pesquisa
  • location_ll - Coordenadas lat/lng (formato: "@lat,lng,zoom")

Exemplo:

search_google_maps(
    query="coffee shops near Central Park",
    location_ll="@40.7829,-73.9654,15z"
)

search_google_maps_place

Obtenha informações detalhadas para um local específico.

Parâmetros:

  • place_id (obrigatório se não houver data_id) - ID do local no Google Maps
  • data_id - Identificador alternativo do local
  • google_domain - Domínio do Google (padrão: "google.com")
  • hl - Código do idioma (padrão: "en")

Exemplo:

search_google_maps_place(
    place_id="ChIJN1t_tDeuEmsRUsoyG83frY4"
)

search_google_maps_reviews

Obtenha avaliações para um local específico.

Parâmetros:

  • place_id (obrigatório se não houver data_id) - ID do local no Google Maps
  • data_id - Identificador alternativo do local
  • sort_by - "most_relevant", "newest", "highest_rating", "lowest_rating"
  • rating - Filtrar por avaliação: "1"-"5"

Exemplo:

search_google_maps_reviews(
    place_id="ChIJN1t_tDeuEmsRUsoyG83frY4",
    sort_by="newest",
    rating="5"
)

Google Events

search_google_events

Pesquise por eventos, shows, conferências e atividades.

Parâmetros:

  • q (obrigatório) - Consulta de pesquisa (ex.: "shows em São Paulo", "conferências de tecnologia")
  • location - Nome do local para resultados localizados
  • chips - Filtro de data ("today", "tomorrow", "week", "weekend", "month") ou tipo de evento
  • gl - Código do país (padrão: "us")
  • hl - Código do idioma (padrão: "en")
  • page - Número da página (padrão: "1")

Exemplo:

search_google_events(
    q="music festivals in Austin",
    chips="weekend",
    location="Austin, TX"
)

Google Flights

search_google_flights

Pesquise voos com filtros abrangentes.

Parâmetros:

  • departure_id (obrigatório) - Código do aeroporto (ex.: "GRU")
  • arrival_id (obrigatório) - Código do aeroporto (ex.: "LAX")
  • outbound_date (obrigatório) - Data de partida (AAAA-MM-DD)
  • flight_type - "one_way", "round_trip", "multi_city"
  • return_date - Data de retorno (obrigatório para round_trip)
  • travel_class - "economy", "premium_economy", "business", "first"
  • stops - "0" (sem escalas), "1", "2"
  • adults - Número de adultos
  • currency - Código da moeda (ex.: "BRL")

Exemplo:

search_google_flights(
    departure_id="JFK",
    arrival_id="LAX",
    outbound_date="2025-12-15",
    return_date="2025-12-22",
    flight_type="round_trip",
    travel_class="economy",
    stops="0",
    adults="2"
)

search_google_flights_calendar

Obtenha o calendário de preços para planejamento flexível de datas.

Parâmetros:

  • flight_type (obrigatório) - "one_way" ou "round_trip"
  • departure_id (obrigatório) - Código do aeroporto
  • arrival_id (obrigatório) - Código do aeroporto
  • outbound_date (obrigatório) - Data de referência
  • return_date - Obrigatório para round_trip

Exemplo:

search_google_flights_calendar(
    flight_type="round_trip",
    departure_id="SFO",
    arrival_id="NYC",
    outbound_date="2025-12-01",
    return_date="2025-12-08"
)

search_google_flights_location_search

Pesquise códigos de aeroportos e locais.

Parâmetros:

  • q (obrigatório) - Consulta de pesquisa (nome do aeroporto, cidade ou código)
  • gl - Código do país (padrão: "us")
  • hl - Código do idioma (padrão: "en")

Exemplo:

search_google_flights_location_search(
    q="Tokyo"
)

search_google_travel_explore

Explore destinos de viagem e encontre inspiração.

Parâmetros:

  • departure_id (obrigatório) - Código do aeroporto de partida ou local
  • arrival_id - Destino (padrão: qualquer lugar)
  • time_period - Período de viagem (ex.: "two_week_trip_in_december")
  • interests - Filtrar por interesses: "popular", "outdoors", "beaches", "museums", "history", "skiing"
  • travel_class - "economy", "premium_economy", "business", "first_class"
  • adults - Número de adultos (padrão: "1")
  • currency - Código da moeda (padrão: "USD")

Exemplo:

search_google_travel_explore(
    departure_id="JFK",
    interests="beaches",
    time_period="two_week_trip_in_december"
)

Google Hotels

search_google_hotels

Pesquise hotéis e hospedagem.

Parâmetros:

  • q (obrigatório) - Consulta de localização
  • check_in_date (obrigatório) - Data de check-in (AAAA-MM-DD)
  • check_out_date (obrigatório) - Data de check-out (AAAA-MM-DD)
  • adults - Número de adultos (padrão: "2")
  • rating - Avaliação mínima: "3", "4", "5"
  • hotel_class - Classificação por estrelas: "2"-"5"
  • price_min / price_max - Faixa de preço
  • amenities - Filtrar por comodidades (ex.: "pool,wifi,parking")
  • free_cancellation - "true" ou "false"

Exemplo:

search_google_hotels(
    q="hotels in Paris",
    check_in_date="2025-12-20",
    check_out_date="2025-12-25",
    adults="2",
    rating="4",
    amenities="wifi,pool",
    price_max="300",
    free_cancellation="true"
)

search_google_hotels_property

Obtenha informações detalhadas para um hotel específico.

Parâmetros:

  • property_token (obrigatório) - ID da propriedade dos resultados da pesquisa
  • check_in_date (obrigatório) - Data de check-in
  • check_out_date (obrigatório) - Data de check-out
  • adults - Número de adultos

Exemplo:

search_google_hotels_property(
    property_token="ChIJd8BlQ2BZwokRAFUEcm_qrcA",
    check_in_date="2025-12-20",
    check_out_date="2025-12-25",
    adults="2"
)

Exemplos de Uso

Exemplo 1: Descubra e Planeje uma Viagem

# 1. Explore destinations from New York
destinations = search_google_travel_explore(
    departure_id="JFK",
    interests="beaches",
    time_period="two_week_trip_in_december"
)

# 2. Get current date and travel dates
dates = get_current_time(return_future_dates=True, future_days=30)
check_in = dates["travel_dates"]["next_week"]
check_out = dates["travel_dates"]["next_month"]

# 3. Search for flights
flights = search_google_flights(
    departure_id="JFK",
    arrival_id="CDG",
    outbound_date=check_in,
    return_date=check_out,
    flight_type="round_trip",
    travel_class="economy",
    adults="2"
)

# 4. Search for hotels
hotels = search_google_hotels(
    q="hotels in Paris",
    check_in_date=check_in,
    check_out_date=check_out,
    adults="2",
    rating="4",
    amenities="wifi,breakfast"
)

# 5. Find nearby restaurants
restaurants = search_google_maps(
    query="restaurants near Eiffel Tower"
)

# 6. Get detailed place info
place_details = search_google_maps_place(
    place_id=restaurants["local_results"][0]["place_id"]
)

# 7. Find local events
events = search_google_events(
    q="concerts in Paris",
    chips="weekend"
)

Exemplo 2: Pesquise com AI Mode

# Get AI-generated overview with sources
result = search_google_ai_mode(
    q="What are the health benefits of Mediterranean diet?",
    location="United States"
)

# Result includes:
# - result["markdown"] - AI overview in markdown format
# - result["text_blocks"] - Structured content blocks
# - result["reference_links"] - Cited sources
# - result["web_results"] - Traditional search results

Exemplo 3: Monitore a Saúde do Serviço

# Check API health and metrics
health = health_check()

print(f"Status: {health['api_status']['status']}")
print(f"Latency: {health['api_status']['latency_ms']}ms")
print(f"Cache hit rate: {health['metrics']['cache_hit_rate']:.2%}")
print(f"Total requests: {health['metrics']['request_count']}")

Desenvolvimento

Executando Testes

# Run all tests
python -m pytest

# Run specific test file
python test_refactored.py

Estrutura do Código

searchAPI-mcp/
├── mcp_server_refactored.py  # Main MCP server with FastMCP
├── config.py                  # Configuration with Pydantic validation
├── client.py                  # HTTP client with pooling, retry, caching
├── requirements.txt           # Python dependencies
├── .env.example              # Example environment variables
└── tests/                    # Test files

Componentes Principais

  • mcp_server_refactored.py - Implementação do servidor MCP usando FastMCP

    • Definições de ferramentas com docstrings abrangentes
    • Verificações de saúde e endpoints de monitoramento
    • Desligamento limpo e gerenciamento de recursos

  • config.py - Gerenciamento de configuração

    • Modelos Pydantic para configuração type-safe
    • Validação de variáveis de ambiente
    • Padrões sensatos com opções de substituição

  • client.py - Cliente HTTP pronto para produção

    • Pool de conexões com httpx
    • Lógica de repetição com backoff exponencial
    • Cache de respostas baseado em TTL
    • Padrão de disjuntor
    • Coleta de métricas

Depuração

Use o MCP Inspector para testar ferramentas:

# Install inspector
npm install -g @modelcontextprotocol/inspector

# Run inspector
npx @modelcontextprotocol/inspector python mcp_server_refactored.py

Defina a variável de ambiente para registro detalhado:

LOG_LEVEL=DEBUG python mcp_server_refactored.py

Solução de Problemas

Problemas Comuns

Problema: Erro "Invalid API key"

  • Solução: Certifique-se de que SEARCHAPI_API_KEY esteja definida corretamente no ambiente ou no arquivo .env
  • Obtenha uma chave de API em https://www.searchapi.io/

Problema: Erro "Circuit breaker is OPEN"

  • Causa: Muitas falhas consecutivas de API
  • Solução: Verifique sua conexão com a internet e a chave de API. Aguarde 60 segundos para o disjuntor redefinir ou reinicie o servidor

Problema: Timeouts de conexão

  • Solução: Aumente o timeout no .env: TIMEOUT=60.0
  • Verifique a conectividade de rede com a SearchAPI.io

Problema: Alta latência

  • Solução: Ative o cache se estiver desativado: ENABLE_CACHE=true
  • Aumente o tamanho do cache: CACHE_MAX_SIZE=5000
  • Verifique a ferramenta health_check para métricas

Problema: Erros de codificação no Windows

  • Solução: Defina a variável de ambiente na configuração do seu cliente MCP: 
    "env": {
  "PYTHONIOENCODING": "utf-8",
  "SEARCHAPI_API_KEY": "your_key"
}

Obtendo Ajuda

Ajuste de Desempenho

Configuração de Cache

Para taxas de acerto de cache mais altas:

CACHE_TTL=7200        # 2 hours
CACHE_MAX_SIZE=5000   # Store more results

Para ambientes com restrição de memória:

CACHE_TTL=1800        # 30 minutes
CACHE_MAX_SIZE=100    # Smaller cache

Pool de Conexões

Para cenários de alto tráfego:

POOL_CONNECTIONS=50
POOL_MAXSIZE=50

Para cenários de baixo tráfego:

POOL_CONNECTIONS=5
POOL_MAXSIZE=5

Considerações de Segurança

⚠️ Notas de Segurança Importantes:

  1. Proteção da Chave de API

    • Nunca envie o arquivo .env para o controle de versão
    • Use variáveis de ambiente em produção
    • Rotacione as chaves de API regularmente

  2. Limitação de Taxa

    • O SearchAPI.io possui limites de taxa baseados no seu plano
    • A lógica de nova tentativa integrada respeita os limites de taxa
    • Monitore o uso com a ferramenta health_check

  3. Privacidade dos Dados

    • As consultas de pesquisa são enviadas ao SearchAPI.io
    • As respostas são armazenadas em cache localmente (configurável)
    • Revise a política de privacidade do SearchAPI.io

Licença

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

Agradecimentos

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request. Para mudanças significativas, abra uma issue primeiro para discutir o que você gostaria de alterar.

  1. Faça um fork do repositório
  2. Crie sua branch de funcionalidade (git checkout -b feature/AmazingFeature)
  3. Faça commit das suas alterações (git commit -m 'Add some AmazingFeature')
  4. Envie para a branch (git push origin feature/AmazingFeature)
  5. Abra um Pull Request

Histórico de Versões

v1.1.0 (Atual)

  • ✅ Novo: Google Maps Place API - Informações detalhadas de lugares
  • ✅ Novo: Google Events API - Pesquisa de eventos e atividades
  • ✅ Novo: Google Travel Explore API - Descoberta de destinos
  • ✅ Novo: Google Flights Location Search API - Consulta de aeroportos
  • ✅ Capacidades aprimoradas de pesquisa para turismo e viagens
  • ✅ Suporte abrangente ao fluxo de trabalho de planejamento de viagens

v1.0.0

  • ✅ Arquitetura pronta para produção com FastMCP
  • ✅ Pool de conexões e lógica de nova tentativa
  • ✅ Cache de respostas com TTL
  • ✅ Padrão de disjuntor (circuit breaker)
  • ✅ Verificações de integridade e métricas abrangentes
  • ✅ Google Search, Vídeos, Modo IA
  • ✅ Google Maps e Avaliações
  • ✅ Google Flights e Calendário
  • ✅ Google Hotels e detalhes de propriedades
  • ✅ Utilitários de tempo para planejamento de viagens

⬆ Voltar ao Topo

Feito com ❤️ para a comunidade MCP