SerpApi MCP

Servidor MCP de SerpApi

Una implementación de servidor del Model Context Protocol (MCP) que se integra con SerpApi para ofrecer resultados completos de motores de búsqueda y extracción de datos.

Funciones

• Búsqueda en varios motores: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay y más
• Recursos de motores: esquemas de parámetros disponibles para cada motor mediante recursos MCP (consulta la herramienta de búsqueda)
• Datos meteorológicos en tiempo real: información meteorológica basada en la ubicación, con pronósticos mediante consultas de búsqueda
• Datos del mercado bursátil: datos financieros de empresas y del mercado mediante la integración de búsqueda
• Procesamiento dinámico de resultados: detecta y da formato automáticamente a distintos tipos de resultados
• Modos de respuesta flexibles: respuestas JSON completas o compactas
• Respuestas JSON (predeterminado): salida JSON estructurada en modo completo o compacto
• Respuestas Markdown: reduce el uso de tokens en un 50 % de media y en más de un 90 % para las API con JSON anidado complejo.
• Interfaz interactiva (MCP Apps): herramientas search_table y search_dashboard opcionales que muestran los resultados como una interfaz interactiva en los hosts compatibles
• Extensión de Claude Desktop: instalación local con un clic desde un paquete MCP (.mcpb); consulta los detalles más abajo

Inicio rápido

El servidor MCP de SerpApi está disponible como servicio alojado en mcp.serpapi.com. Para conectarte, debes proporcionar una clave de API. Puedes encontrarla en tu panel de SerpApi.

Puedes configurar Claude Desktop para que use el servidor alojado:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

También puedes añadir el servidor alojado a estos clientes MCP:

OpenClaw

openclaw mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp --transport streamable-http

Claude Code

claude mcp add --transport http serpapi https://mcp.serpapi.com/mcp --header "Authorization: Bearer YOUR_SERPAPI_API_KEY"

Hermes

hermes mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp

Codex (lee la clave de SERPAPI_API_KEY en tu shell)

codex mcp add serpapi --url https://mcp.serpapi.com/mcp --bearer-token-env-var SERPAPI_API_KEY

Alojamiento propio

git clone https://github.com/serpapi/serpapi-mcp.git
cd serpapi-mcp
uv sync && uv run src/server.py

Configura Claude Desktop:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "http://localhost:8000/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

Obtén tu clave de API: serpapi.com/manage-api-key

Extensión de Claude Desktop (paquete MCP)

Para instalarla localmente con un clic, descarga el paquete .mcpb de la versión más reciente y ábrelo con Claude Desktop (o arrástralo a Configuración → Extensiones). Claude Desktop te pedirá la clave de API de SerpApi durante la instalación, la guardará como un ajuste confidencial y ejecutará el servidor localmente mediante stdio. Durante la instalación, aprovisiona Python y las dependencias con uv. El mismo paquete funciona en macOS, Windows y Linux.

El mismo punto de entrada stdio funciona con cualquier host MCP local que inicie servidores como subprocesos:

{
  "mcpServers": {
    "serpapi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/serpapi-mcp", "--frozen", "--no-dev", "src/stdio.py"],
      "env": { "SERPAPI_API_KEY": "YOUR_SERPAPI_API_KEY" }
    }
  }
}

Autenticación

Se admiten dos métodos:

• Mediante encabezado: Authorization: Bearer YOUR_API_KEY (recomendado: la clave no aparece en las URL ni en los registros)
• Mediante ruta: /YOUR_API_KEY/mcp, para clientes que no pueden configurar encabezados

Ejemplos:

# Header-based
curl "https://mcp.serpapi.com/mcp" -H "Authorization: Bearer your_key" -d '...'

# Path-based
curl "https://mcp.serpapi.com/your_key/mcp" -d '...'

No se necesita una clave para conectarse, enumerar herramientas o leer recursos. search y las herramientas de App la requieren y devuelven un error si no se proporciona.

Herramienta de búsqueda

El servidor MCP tiene una herramienta de búsqueda principal compatible con todos los motores y tipos de resultados de SerpApi. Puedes consultar todos los parámetros disponibles en la referencia de la API de SerpApi. Los esquemas de parámetros de los motores también están disponibles como recursos MCP: serpapi://engines (índice) y serpapi://engines/<engine>. Los clientes compatibles con la completación de argumentos pueden solicitar sugerencias de nombres de motores para serpapi://engines/{engine_name}. Por ejemplo, el prefijo google_f sugiere identificadores de motores coincidentes. Esto completa el parámetro de URI del recurso, no las consultas de búsqueda arbitrarias.

Los parámetros que puedes proporcionar dependen de cada motor de API. A continuación se muestran algunos ejemplos:

• params.q (obligatorio): consulta de búsqueda
• params.engine: motor de búsqueda (predeterminado: "google_light")
• params.location: filtro geográfico
• params.output: formato de respuesta; omítelo para usar JSON (predeterminado) o establece "md" para Markdown
• mode: modo de respuesta; "compact" elimina los metadatos del JSON, mientras que Markdown se devuelve sin cambios
• ...consulta otros parámetros en la referencia de la API de SerpApi

Ejemplos:

{"name": "search", "arguments": {"params": {"q": "coffee shops", "location": "Austin, TX"}}}
{"name": "search", "arguments": {"params": {"q": "weather in London"}}}
{"name": "search", "arguments": {"params": {"q": "AAPL stock"}}}
{"name": "search", "arguments": {"params": {"q": "news"}, "mode": "compact"}}
{"name": "search", "arguments": {"params": {"q": "detailed search"}, "mode": "complete"}}
{"name": "search", "arguments": {"params": {"q": "news", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "amazon", "k": "mechanical keyboards", "amazon_domain": "amazon.com", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "google_scholar", "q": "retrieval augmented generation"}}}
{"name": "search", "arguments": {"params": {"engine": "youtube", "search_query": "how to make espresso"}}}
{"name": "search", "arguments": {"params": {"engine": "apple_app_store", "term": "habit tracker"}}}
{"name": "search", "arguments": {"params": {"engine": "ebay", "_nkw": "vintage mechanical keyboard"}}}

Motores compatibles: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay y más (consulta serpapi://engines).

Tipos de resultados: cuadros de respuesta, resultados orgánicos, noticias, imágenes y compras; se detectan y se les da formato automáticamente.

Las respuestas de búsqueda conservan la cadena MCP structuredContent.result existente e incluyen la misma cadena en el contenido de texto. En la salida JSON, result contiene JSON serializado; los clientes existentes pueden seguir analizándolo con JSON.parse(response.structuredContent.result). En la salida Markdown, contiene el Markdown sin cambios. Los errores y las cancelaciones usan el mismo contenedor. Si falla la ejecución de una búsqueda, se establece isError: true; los clientes que usan el método de alto nivel call_tool() de FastMCP deben gestionar ToolError o usar call_tool_mcp() para inspeccionar el indicador del resultado. Consulta Resultados de herramientas MCP.

search usa el catálogo de motores y reglas específicas de cada motor para identificar los parámetros que faltan. Los clientes compatibles con MCP 2026-07-28 reciben un formulario antes de que se ejecute cualquier búsqueda. Las respuestas aceptadas se validan; si se rechaza o cancela el formulario, no se ejecuta ninguna búsqueda. Los clientes heredados y los que no admiten la solicitud de datos mediante formularios reciben un error que enumera los parámetros que faltan, para que el agente pueda solicitarlos en la conversación. Consulta Solicitudes de entrada de MCP.

• Google Flights: identificadores de origen y destino, fecha de salida y fecha de regreso para viajes de ida y vuelta. Se validan las fechas y los identificadores de aeropuerto. Las búsquedas basadas en tokens, los itinerarios con varias ciudades y selected_flights_json conservan su comportamiento actual.
• Google Hotels: destino o consulta de hotel, fecha de entrada y fecha de salida. La fecha de salida debe ser posterior a la de entrada. El número de huéspedes y otros filtros opcionales conservan los valores del llamador o los valores predeterminados de la API.
• Google Maps Directions: direcciones de origen y destino que falten. Las coordenadas o los ID de datos de lugares proporcionados ya satisfacen el extremo correspondiente.
• Los demás motores del catálogo usan sus campos obligatorios, como search_query de YouTube, find_loc de Yelp y k de Amazon. Las reglas de los motores tienen en cuenta los valores predeterminados y las alternativas conocidas, incluidos los nodos de categoría de Amazon, las categorías de eBay y las búsquedas de citas de Google Scholar.

Si una respuesta introduce otro requisito, la herramienta enumera los campos restantes para que el agente los proporcione en una nueva llamada. Los formularios admiten campos de texto, números, valores booleanos y opciones únicas; los campos complejos no compatibles generan un error de parámetro faltante. Los motores desconocidos se envían directamente a SerpApi.

Herramienta de extracción

La herramienta extract lee páginas web y devuelve su contenido como JSON estructurado o Markdown. Puedes extraer una sola página, descubrir las URL de un sitio web o rastrear varias páginas. Consulta todos los parámetros disponibles en la referencia de la API de Extract o en el recurso serpapi://engines/extract.

Algunos parámetros que puedes proporcionar:

• params.url (obligatorio): URL de una página o sitio web
• params.mode: modo de extracción; "scrape" (predeterminado) lee una página, "map" descubre URL y "crawl" extrae varias páginas
• params.include_markdown: incluye el contenido de la página en formato Markdown; de forma predeterminada, es true para scrape y crawl, o establece false para desactivarlo
• params.output: formato de respuesta; de forma predeterminada, es "json" en modo completo y "md" en modo compacto. Establécelo explícitamente para anular el formato.
• params.max_pages: número máximo de páginas que se rastrearán, incluida la página inicial (predeterminado: 10, máximo: 100)
• params.json_restrictor: elige qué campos devolver, como "markdown,error"
• mode: modo de respuesta; "complete" (predeterminado) devuelve la respuesta completa. "compact" usa Markdown nativo de forma predeterminada. Con un valor explícito de params.output="json", la extracción compacta de una sola página conserva el campo de nivel superior markdown cuando está presente y mantiene los errores de la API. Las respuestas sin Markdown, incluidos los resultados redirigidos a otro motor, conservan sus datos y eliminan los metadatos. Los valores explícitos de params.json_restrictor y params.include_markdown=false tienen prioridad al usar JSON. En los modos map y crawl, el JSON compacto elimina los metadatos. La salida Markdown se devuelve sin cambios.

Ejemplos:

{"name": "extract", "arguments": {"params": {"url": "https://example.com"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com"}, "mode": "compact"}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "output": "md"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "map"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "crawl", "max_pages": 2}}}

Para obtener el contenido de una sola página en Markdown nativo, usa mode="compact". Añade params.output="json" para recibir JSON que contenga el campo markdown. El JSON completo incluye ese campo de forma predeterminada; el JSON de crawl lo incluye en cada entrada pages. Si estableces params.output="json" y params.include_markdown=false, se conservan los demás campos estructurados y se omite Markdown.

El rastreo consume un crédito de búsqueda por cada página extraída correctamente en una solicitud sin caché. Usa params.max_pages para limitar el número de páginas que se extraen.

Interfaz interactiva (MCP Apps)

La herramienta search devuelve JSON de forma predeterminada. En los hosts compatibles con la extensión MCP Apps (SEP-1865), dos herramientas opcionales muestran los resultados como una interfaz interactiva directamente en la conversación, de modo que el JSON SERP voluminoso nunca entra en la ventana de contexto del modelo:

• search_table: resultados orgánicos en una tabla ordenable y con búsqueda.
• search_dashboard: métricas resumidas, un gráfico de desglose por fuente y una tabla de resultados con un panel de detalles que se abre al hacer clic.

Ambas aceptan el mismo params que search. Los hosts que no admiten MCP Apps simplemente ignoran estas herramientas.

Solución de problemas

• «Falta la clave de API»: incluye la clave en la ruta de la URL /{YOUR_KEY}/mcp o en el encabezado Bearer YOUR_KEY
• «Clave no válida»: verifícala en serpapi.com/dashboard
• «Se superó el límite de solicitudes»: espera o mejora tu plan de SerpApi
• «No hay resultados»: prueba con otra consulta o motor

Política de privacidad

• Enviado: solo los parámetros que el host MCP pasa a una llamada de herramienta. El servidor nunca ve el resto de la conversación ni los archivos, la memoria o el historial del host.
• Reenviado: cada búsqueda se envía a serpapi.com con tu clave de API; los resultados se devuelven sin cambios. Consulta la Política de privacidad de SerpApi para saber cómo gestiona SerpApi las búsquedas y las cuentas.
• Conservado: mcp.serpapi.com registra métricas de solicitudes (método, código de estado y duración) y no almacena consultas ni resultados. Una clave en la ruta de la URL puede aparecer en los registros de solicitudes, por lo que se recomienda usar el encabezado.
• Paquete local: la extensión de Claude Desktop se ejecuta en tu equipo, guarda la clave en la configuración de Claude Desktop y llama directamente a serpapi.com. Nada pasa por mcp.serpapi.com.
• Contacto: privacy@serpapi.com o abre una incidencia.

Contribuciones

Consulta CONTRIBUTING.md para obtener información sobre la configuración del entorno de desarrollo, los comandos para actualizar esquemas, las pruebas, las compilaciones de Docker y MCP Bundle, y las versiones.

Licencia

Licencia MIT: consulta el archivo LICENSE para obtener más información.