SearchAPI

Proporciona acceso estandarizado a Google Maps, Google Flights, Google Hotels y otros servicios a través de SearchAPI.

GitHub
74
Prueba este MCPPatrocinado

Documentación

Servidor MCP de SearchAPI

License: MIT Python 3.10+ FastMCP

Un servidor de Model Context Protocol (MCP) listo para producción que proporciona capacidades de búsqueda integrales a través de SearchAPI.io. Permite que los asistentes de IA busquen en Google, Mapas, Vuelos, Hoteles y más, con caché integrada, lógica de reintentos y cortacircuitos.

Un servidor de búsqueda de nivel de producción basado en Model Context Protocol (MCP) que ofrece funciones de búsqueda completas a través de SearchAPI.io. Permite que los asistentes de IA busquen en Google, Mapas, Vuelos, Hoteles y más, con caché integrada, lógica de reintentos y cortacircuitos.

Características • Inicio rápido • Instalación • Configuración • Herramientas disponibles

Características

🔍 Motores de búsqueda

  • Búsqueda de Google - Resultados web, grafo de conocimiento, cajas de respuesta, preguntas relacionadas
  • Videos de Google - Búsqueda de videos con filtros por duración, fuente y fecha de publicación
  • Modo IA de Google - Resúmenes generados por IA con fuentes citadas y contenido estructurado
  • Google Maps - Lugares, negocios, reseñas y detalles de ubicación
  • Lugar en Google Maps - Información detallada de ubicaciones específicas (horarios, fotos, servicios)
  • Eventos de Google - Encuentra conciertos, conferencias, festivales y actividades locales
  • Vuelos de Google - Búsqueda de vuelos con filtros completos y calendarios de precios
  • Búsqueda de ubicación de vuelos de Google - Consulta de códigos de aeropuerto y autocompletado
  • Exploración de viajes de Google - Descubre destinos e inspiración para viajar
  • Hoteles de Google - Búsqueda de alojamiento con servicios, calificaciones y filtros de precio

🏗️ Arquitectura lista para producción

  • Agrupación de conexiones - Gestión eficiente de conexiones HTTP con httpx
  • Caché de respuestas - Caché configurable basada en TTL con expulsión LRU
  • Lógica de reintentos - Retroceso exponencial para fallos transitorios
  • Cortacircuitos - Patrón a prueba de fallos que previene fallos en cascada
  • Recopilación de métricas - Conteo de solicitudes, latencias, tasas de acierto de caché, seguimiento de errores
  • Comprobaciones de salud - Monitoreo de la conectividad de la API y el estado del servicio

⚙️ Configuración y monitoreo

  • Validación Pydantic - Configuración con seguridad de tipos y soporte de variables de entorno
  • Registro estructurado - Niveles de registro configurables con seguimiento detallado de solicitudes
  • Gestión de recursos - Limpieza automática y apagado ordenado
  • Variables de entorno - Configuración flexible para diferentes despliegues

Inicio rápido

Requisitos previos

Instalación con UV (Recomendado)

La forma más rápida de comenzar es 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

Instalación

Método 1: UV (Recomendado)

UV es el método más rápido y 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: Desde el código fuente

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

Configuración

Variables de entorno

Crea un archivo .env en la raíz del proyecto:

# 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

Configuración del cliente MCP

Claude Desktop

Agrega a tu archivo de configuración de Claude Desktop:

Ubicación:

  • 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 directamente:

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

Usando entorno 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)

Agrega a .vscode/mcp.json en tu espacio de trabajo o usa el 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"
      }
    }
  }
}

Con 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

Agrega 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 (Extensión de VS Code)

En la configuración de Cline, agrega a 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 cualquier cliente compatible con 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

Herramientas disponibles

Salud y monitoreo

health_check

Comprueba la salud y el rendimiento del servicio de SearchAPI.

Devuelve:

  • Estado de conectividad de la API
  • Latencia de respuesta
  • Estado del cortacircuitos
  • Estadísticas de caché
  • Métricas de solicitudes

Ejemplo:

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

Utilidades de hora y fecha

get_current_time

Obtén la hora actual y sugerencias de fechas de viaje. Esencial para reservas de vuelos y hoteles.

Parámetros:

  • format - Formato de fecha: "iso", "slash", "chinese", "timestamp", "full"
  • days_offset - Días a partir de hoy (puede ser negativo)
  • return_future_dates - Devuelve un arreglo de fechas futuras
  • future_days - Número de fechas futuras (si return_future_dates=true)

Ejemplo:

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

Búsqueda de Google

search_google

Busca en Google resultados web, grafos de conocimiento y cajas de respuesta.

Parámetros:

  • q (obligatorio) - Consulta de búsqueda
  • location - Nombre de ubicación (p. ej., "Nueva York, NY")
  • gl - Código de país (predeterminado: "us")
  • hl - Código de idioma (predeterminado: "en")
  • time_period - Filtro de tiempo: "last_hour", "last_day", "last_week", "last_month", "last_year"
  • num - Resultados por página (predeterminado: "10")
  • safe - Búsqueda segura: "off", "active"

Ejemplo:

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

search_google_videos

Busca videos en Google Videos.

Parámetros: Similares a search_google con filtros específicos de video

  • q (obligatorio) - Consulta de búsqueda
  • time_period - Filtro por fecha de publicación
  • device - "desktop" o "mobile"

Ejemplo:

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

search_google_ai_mode

Busca con resúmenes generados por IA y fuentes citadas.

Parámetros:

  • q - Consulta de búsqueda (obligatorio a menos que se proporcione url)
  • url - URL de imagen para buscar
  • location - Ubicación para resultados localizados

Devuelve:

  • Resumen generado por IA con citas
  • Bloques de contenido estructurado (párrafos, listas, tablas, código)
  • Enlaces de referencia
  • Resultados web

Ejemplo:

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

Google Maps

search_google_maps

Busca lugares, negocios y servicios.

Parámetros:

  • query (obligatorio) - Consulta de búsqueda
  • location_ll - Coordenadas lat/lng (formato: "@lat,lng,zoom")

Ejemplo:

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

search_google_maps_place

Obtén información detallada de un lugar específico.

Parámetros:

  • place_id (obligatorio si no hay data_id) - ID de lugar de Google Maps
  • data_id - Identificador alternativo de lugar
  • google_domain - Dominio de Google (predeterminado: "google.com")
  • hl - Código de idioma (predeterminado: "en")

Ejemplo:

search_google_maps_place(
    place_id="ChIJN1t_tDeuEmsRUsoyG83frY4"
)

search_google_maps_reviews

Obtén reseñas de un lugar específico.

Parámetros:

  • place_id (obligatorio si no hay data_id) - ID de lugar de Google Maps
  • data_id - Identificador alternativo de lugar
  • sort_by - "most_relevant", "newest", "highest_rating", "lowest_rating"
  • rating - Filtro por calificación: "1"-"5"

Ejemplo:

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

Eventos de Google

search_google_events

Busca eventos, conciertos, conferencias y actividades.

Parámetros:

  • q (obligatorio) - Consulta de búsqueda (p. ej., "conciertos en CDMX", "conferencias tecnológicas")
  • location - Nombre de ubicación para resultados localizados
  • chips - Filtro de fecha ("today", "tomorrow", "week", "weekend", "month") o tipo de evento
  • gl - Código de país (predeterminado: "us")
  • hl - Código de idioma (predeterminado: "en")
  • page - Número de página (predeterminado: "1")

Ejemplo:

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

Vuelos de Google

search_google_flights

Busca vuelos con filtros completos.

Parámetros:

  • departure_id (obligatorio) - Código de aeropuerto (p. ej., "JFK")
  • arrival_id (obligatorio) - Código de aeropuerto (p. ej., "LAX")
  • outbound_date (obligatorio) - Fecha de salida (AAAA-MM-DD)
  • flight_type - "one_way", "round_trip", "multi_city"
  • return_date - Fecha de regreso (obligatoria para round_trip)
  • travel_class - "economy", "premium_economy", "business", "first"
  • stops - "0" (sin escalas), "1", "2"
  • adults - Número de adultos
  • currency - Código de moneda (p. ej., "USD")

Ejemplo:

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

Obtén el calendario de precios para planificar fechas flexibles.

Parámetros:

  • flight_type (obligatorio) - "one_way" o "round_trip"
  • departure_id (obligatorio) - Código de aeropuerto
  • arrival_id (obligatorio) - Código de aeropuerto
  • outbound_date (obligatorio) - Fecha de referencia
  • return_date - Obligatorio para round_trip

Ejemplo:

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

Busca códigos de aeropuerto y ubicaciones.

Parámetros:

  • q (obligatorio) - Consulta de búsqueda (nombre de aeropuerto, ciudad o código)
  • gl - Código de país (predeterminado: "us")
  • hl - Código de idioma (predeterminado: "en")

Ejemplo:

search_google_flights_location_search(
    q="Tokyo"
)

search_google_travel_explore

Explora destinos de viaje y encuentra inspiración.

Parámetros:

  • departure_id (obligatorio) - Código de aeropuerto de salida o ubicación
  • arrival_id - Destino (predeterminado: cualquier lugar)
  • time_period - Período de viaje (p. ej., "two_week_trip_in_december")
  • interests - Filtro por intereses: "popular", "outdoors", "beaches", "museums", "history", "skiing"
  • travel_class - "economy", "premium_economy", "business", "first_class"
  • adults - Número de adultos (predeterminado: "1")
  • currency - Código de moneda (predeterminado: "USD")

Ejemplo:

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

Hoteles de Google

search_google_hotels

Busca hoteles y alojamiento.

Parámetros:

  • q (obligatorio) - Consulta de ubicación
  • check_in_date (obligatorio) - Fecha de entrada (AAAA-MM-DD)
  • check_out_date (obligatorio) - Fecha de salida (AAAA-MM-DD)
  • adults - Número de adultos (predeterminado: "2")
  • rating - Calificación mínima: "3", "4", "5"
  • hotel_class - Calificación por estrellas: "2"-"5"
  • price_min / price_max - Rango de precios
  • amenities - Filtro por servicios (p. ej., "pool,wifi,parking")
  • free_cancellation - "true" o "false"

Ejemplo:

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

Obtén información detallada de un hotel específico.

Parámetros:

  • property_token (obligatorio) - ID de propiedad de los resultados de búsqueda
  • check_in_date (obligatorio) - Fecha de entrada
  • check_out_date (obligatorio) - Fecha de salida
  • adults - Número de adultos

Ejemplo:

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

Ejemplos de uso

Ejemplo 1: Descubre y planifica un viaje

# 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"
)

Ejemplo 2: Investiga con el modo IA

# 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

Ejemplo 3: Monitorea la salud del servicio

# 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']}")

Desarrollo

Ejecutar pruebas

# Run all tests
python -m pytest

# Run specific test file
python test_refactored.py

Estructura del 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 clave

  • mcp_server_refactored.py - Implementación del servidor MCP usando FastMCP

    • Definiciones de herramientas con documentación completa
    • Comprobaciones de salud y endpoints de monitoreo
    • Apagado limpio y gestión de recursos

  • config.py - Gestión de configuración

    • Modelos Pydantic para configuración con seguridad de tipos
    • Validación de variables de entorno
    • Valores predeterminados sensatos con opciones de anulación

  • client.py - Cliente HTTP listo para producción

    • Agrupación de conexiones con httpx
    • Lógica de reintentos con retroceso exponencial
    • Caché de respuestas basada en TTL
    • Patrón de cortacircuitos
    • Recopilación de métricas

Depuración

Usa el Inspector de MCP para probar herramientas:

# Install inspector
npm install -g @modelcontextprotocol/inspector

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

Configura la variable de entorno para registro detallado:

LOG_LEVEL=DEBUG python mcp_server_refactored.py

Solución de problemas

Problemas comunes

Problema: Error de "clave de API no válida"

  • Solución: Asegúrate de que SEARCHAPI_API_KEY esté configurada correctamente en el entorno o en el archivo .env
  • Obtén una clave de API en https://www.searchapi.io/

Problema: Error de "cortacircuitos ABIERTO"

  • Causa: Demasiados fallos consecutivos de la API
  • Solución: Comprueba tu conexión a internet y tu clave de API. Espera 60 segundos para que el cortacircuitos se restablezca, o reinicia el servidor

Problema: Tiempos de espera de conexión

  • Solución: Aumenta el tiempo de espera en .env: TIMEOUT=60.0
  • Comprueba la conectividad de red con SearchAPI.io

Problema: Latencia alta

  • Solución: Habilita la caché si está deshabilitada: ENABLE_CACHE=true
  • Aumenta el tamaño de la caché: CACHE_MAX_SIZE=5000
  • Consulta la herramienta health_check para ver las métricas

Problema: Errores de codificación en Windows

  • Solución: Configura la variable de entorno en la configuración de tu cliente MCP: 
    "env": {
  "PYTHONIOENCODING": "utf-8",
  "SEARCHAPI_API_KEY": "your_key"
}

Obtener ayuda

Ajuste de Rendimiento

Configuración de Caché

Para mayores tasas de acierto de caché:

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

Para entornos con memoria limitada:

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

Grupo de Conexiones

Para escenarios de alto tráfico:

POOL_CONNECTIONS=50
POOL_MAXSIZE=50

Para escenarios de bajo tráfico:

POOL_CONNECTIONS=5
POOL_MAXSIZE=5

Consideraciones de Seguridad

⚠️ Notas de Seguridad Importantes:

  1. Protección de la Clave API

    • Nunca confirmes el archivo .env en el control de versiones
    • Usa variables de entorno en producción
    • Rota las claves API regularmente

  2. Límite de Tasa

    • SearchAPI.io tiene límites de tasa según tu plan
    • La lógica de reintento integrada respeta los límites de tasa
    • Monitorea el uso con la herramienta health_check

  3. Privacidad de Datos

    • Las consultas de búsqueda se envían a SearchAPI.io
    • Las respuestas se almacenan en caché localmente (configurable)
    • Revisa la política de privacidad de SearchAPI.io

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENCIA para más detalles.

Agradecimientos

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request. Para cambios importantes, abre primero un issue para discutir lo que te gustaría cambiar.

  1. Haz un fork del repositorio
  2. Crea tu rama de características (git checkout -b feature/AmazingFeature)
  3. Confirma tus cambios (git commit -m 'Add some AmazingFeature')
  4. Sube los cambios a la rama (git push origin feature/AmazingFeature)
  5. Abre un Pull Request

Registro de Cambios

v1.1.0 (Actual)

  • ✅ Nuevo: Google Maps Place API - Información detallada de lugares
  • ✅ Nuevo: Google Events API - Búsqueda de eventos y actividades
  • ✅ Nuevo: Google Travel Explore API - Descubrimiento de destinos
  • ✅ Nuevo: Google Flights Location Search API - Búsqueda de aeropuertos
  • ✅ Capacidades mejoradas de investigación turística y de viajes
  • ✅ Soporte integral del flujo de trabajo de planificación de viajes

v1.0.0

  • ✅ Arquitectura lista para producción con FastMCP
  • ✅ Grupo de conexiones y lógica de reintento
  • ✅ Caché de respuestas con TTL
  • ✅ Patrón de interruptor de circuito
  • ✅ Verificaciones de salud y métricas integrales
  • ✅ Google Search, Videos, Modo IA
  • ✅ Google Maps y Reseñas
  • ✅ Google Flights y Calendario
  • ✅ Google Hotels y detalles de propiedades
  • ✅ Utilidades de tiempo para planificación de viajes

⬆ Volver al Inicio

Hecho con ❤️ para la comunidad MCP