SerpApi MCP

Servidor MCP de SerpApi

Una implementación de servidor de Protocolo de Contexto de Modelo (MCP) que se integra con SerpApi para obtener resultados completos de motores de búsqueda y extracción de datos.

Características

• Búsqueda Multi-Motor: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay y más
• Recursos de Motores: Esquemas de parámetros por motor disponibles a través de recursos MCP (ver Herramienta de Búsqueda)
• Datos Meteorológicos en Tiempo Real: Clima basado en ubicación con pronósticos mediante consultas de búsqueda
• Datos del Mercado de Valores: Finanzas de empresas y datos de mercado mediante integración de búsqueda
• Procesamiento Dinámico de Resultados: Detecta y formatea automáticamente diferentes tipos de resultados
• Modos de Respuesta Flexibles: Respuestas JSON completas o compactas
• Respuestas JSON (predeterminado): Salida JSON estructurada con modos completos o compactos
• Respuestas Markdown: Reduce el uso de tokens en un 50% en promedio y más del 90% para APIs con JSON anidado complejo.
• Interfaz de Usuario Interactiva (Aplicaciones MCP): Herramientas opcionales search_table y search_dashboard que renderizan resultados como una interfaz de usuario interactiva en hosts compatibles
• Extensión para Claude Desktop: Instalación local con un clic desde un Paquete MCP (.mcpb), ver más abajo

Inicio Rápido

El Servidor MCP de SerpApi está disponible como un servicio alojado en mcp.serpapi.com. Para conectarte, necesitas proporcionar una clave de API. Puedes encontrar tu clave de API en tu panel de SerpApi.

Puedes configurar Claude Desktop para usar el servidor alojado:

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

También puedes agregar 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

Autoalojamiento

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 para Claude Desktop (Paquete MCP)

Para una instalación local con un clic, descarga el paquete .mcpb desde la última versión (o constrúyelo como se indica abajo) y ábrelo con Claude Desktop (o arrástralo a Configuración → Extensiones). Claude Desktop solicita tu clave de API de SerpApi durante la instalación, la almacena como una configuración sensible y ejecuta el servidor localmente a través de stdio. El paquete utiliza el runtime MCPB uv: incluye solo el código fuente, pyproject.toml y uv.lock, y Claude Desktop aprovisiona Python y las dependencias bloqueadas con uv en el momento de la instalación, por lo que no se incluye nada adicional y un solo paquete funciona en macOS, Windows y Linux.

uv run mcpb/build.py   # needs Node.js for the MCPB CLI; writes dist/serpapi-mcp-<version>.mcpb

Todo lo relacionado con el paquete se encuentra en mcpb/, además de .mcpbignore en la raíz del proyecto. La compilación regenera los esquemas de motores desde el SerpApi Playground (--no-rebuild-engines incluye engines/ del árbol de trabajo en su lugar), valida mcpb/manifest.json, empaqueta los archivos rastreados por git menos .mcpbignore con el manifiesto en la raíz del paquete, luego lo instala en un directorio temporal y lo inicia a través de stdio para asegurarse de que funcione (--no-smoke omite ese último paso). El paquete solo se compila en el momento de la versión: enviar una etiqueta v<version> ejecuta el flujo de trabajo de versión, que ejecuta el conjunto de pruebas y luego despliega el servidor alojado, publica la entrada del Registro MCP y compila el paquete y lo adjunta a la versión de GitHub. Las solicitudes de extracción ejecutan las pruebas de manifiesto y punto de entrada stdio en tests/test_mcpb.py pero no empaquetan un paquete.

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

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

• Basado en encabezado: Authorization: Bearer YOUR_API_KEY (recomendado: la clave no aparece en URLs ni registros)
• Basado en 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 clave para conectarse, listar herramientas o leer recursos. search y las herramientas de Aplicaciones necesitan una y devuelven un error sin ella.

Herramienta de Búsqueda

El servidor MCP tiene una herramienta principal de Búsqueda que admite todos los motores y tipos de resultados de SerpApi. Puedes encontrar todos los parámetros disponibles en la referencia de API de SerpApi. Los esquemas de parámetros de motores también se exponen como recursos MCP: serpapi://engines (índice) y serpapi://engines/<engine>. Los clientes que admiten completado 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 URI del recurso, no consultas de búsqueda arbitrarias.

Los parámetros que puedes proporcionar son específicos para cada motor de API. A continuación se proporcionan algunos parámetros de ejemplo:

• 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; omitir para JSON (predeterminado), o configurar en "md" para Markdown
• mode: Modo de respuesta; "compact" elimina metadatos del JSON, mientras que Markdown se devuelve sin cambios
• ...ver otros parámetros en la referencia de 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 admitidos: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay y más (ver serpapi://engines).

Tipos de resultados: Cajas de respuesta, resultados orgánicos, noticias, imágenes, compras: detectados y formateados automáticamente.

Las respuestas de búsqueda conservan la cadena structuredContent.result MCP existente e incluyen la misma cadena en el contenido de texto. Para salida JSON, result contiene JSON serializado; los clientes existentes pueden continuar analizándolo con JSON.parse(response.structuredContent.result). Para salida Markdown, contiene el Markdown sin cambios. Los errores y cancelaciones usan el mismo envoltorio. Las fallas de ejecución de búsqueda configuran isError: true; los clientes que usan el call_tool() de alto nivel de FastMCP deben manejar ToolError, o usar call_tool_mcp() para inspeccionar el indicador de resultado. Ver resultados de herramientas MCP.

search usa el catálogo de motores y reglas específicas de motores para identificar parámetros faltantes. Los clientes que admiten MCP 2026-07-28 reciben un formulario antes de que se ejecute cualquier búsqueda. Las respuestas aceptadas se validan; rechazar o cancelar no ejecuta ninguna búsqueda. Los clientes heredados y los clientes sin obtención de formularios reciben un error que enumera los parámetros faltantes para que el agente pueda preguntar en la conversación. Ver solicitudes de entrada MCP.

• Google Flights: identificadores de salida y llegada, fecha de salida y fecha de regreso para viajes de ida y vuelta. Se verifican fechas e identificadores de aeropuertos. Las búsquedas basadas en tokens, itinerarios de múltiples ciudades y selected_flights_json conservan su comportamiento existente.
• Google Hotels: destino o consulta de hotel, fecha de entrada y fecha de salida. La salida debe ser posterior a la entrada. Los recuentos de huéspedes y otros filtros opcionales mantienen los valores del llamador o los valores predeterminados de la API.
• Google Maps Directions: faltan direcciones de inicio y destino. Las coordenadas o identificadores de datos de lugares ya proporcionados satisfacen el punto final correspondiente.
• Otros motores del catálogo usan sus campos obligatorios, como search_query de YouTube, find_loc de Yelp y k de Amazon. Las reglas de motores tienen en cuenta valores predeterminados y alternativas conocidos, incluidos nodos de categoría de Amazon, categorías de eBay y búsquedas de citas de Google Scholar.

El formulario se deriva de los argumentos originales en cada solicitud. No usa requestState ni almacenamiento de continuación específico del proceso, por lo que un reintento puede ejecutarse en otra réplica sin una clave de protección de estado compartido. La autenticación se aplica en cada solicitud HTTP, y solo se usan respuestas para los campos solicitados. Si una respuesta introduce otro requisito, la herramienta enumera los campos restantes para que el agente los proporcione en una nueva llamada.

Para extender la búsqueda guiada, agrega campos obligatorios, descripciones, tipos y opciones al archivo engines/<engine>.json del motor. Agrega una entrada EngineInputRules en src/engine_input_rules.py cuando los requisitos dependan de otros parámetros, valores predeterminados o alternativas. El manejador MCP compartido en src/search_input.py no necesita ramas específicas de motores. Los formularios admiten cadenas, números, booleanos y campos de opción única; los campos complejos no admitidos reciben el error de parámetro faltante. Los motores desconocidos pasan directamente a SerpApi.

Interfaz de Usuario Interactiva (Aplicaciones MCP)

La herramienta search devuelve JSON por defecto. Para hosts que admiten la extensión de Aplicaciones MCP (SEP-1865), dos herramientas opcionales renderizan resultados como una interfaz de usuario interactiva directamente en la conversación, por lo que el JSON SERP completo nunca entra en la ventana de contexto del modelo:

• search_table: resultados orgánicos como una tabla ordenable y buscable.
• search_dashboard: métricas de resumen, un gráfico de desglose de fuentes y una tabla de resultados con un panel de detalles expandible al hacer clic.

Ambas aceptan los mismos params que search. Los hosts que no admiten Aplicaciones MCP simplemente ignoran estas herramientas.

Vista previa local sin un host MCP:

uv run fastmcp dev apps src/server.py

Desarrollo

# Local development
uv sync && uv run src/server.py

# Docker
docker build -t serpapi-mcp . && docker run -p 8000:8000 serpapi-mcp

# Build the Claude Desktop extension (MCP Bundle); rebuilds engines, needs Node.js for the MCPB CLI
uv run mcpb/build.py

# Release: update pyproject.toml, server.json, mcpb/manifest.json and uv.lock together.
uv run --no-sync scripts/bump_version.py 2.0.0
# Review and commit the changes before tagging the release.
# Nothing ships on a plain push to main. The tag runs the release workflow, which runs the test
# suite and then deploys the hosted server, publishes server.json to the MCP Registry, and builds
# the MCP Bundle and attaches it to the GitHub release.
git tag v2.0.0 && git push origin v2.0.0

# Regenerate engine resources (Playground scrape)
python build-engines.py

# Testing with MCP Inspector
npx @modelcontextprotocol/inspector
# Configure: URL mcp.serpapi.com/YOUR_KEY/mcp, Transport "Streamable HTTP transport"

Solución de Problemas

• "Falta clave de API": Incluye la clave en la ruta URL /{YOUR_KEY}/mcp o en el encabezado Bearer YOUR_KEY
• "Clave inválida": Verifica en serpapi.com/dashboard
• "Límite de velocidad excedido": Espera o mejora tu plan de SerpApi
• "Sin resultados": Prueba con una consulta o motor diferente

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 archivos, memoria o historial en el host.
• Reenviado: cada búsqueda va a serpapi.com con tu clave de API; los resultados regresan sin cambios. Consulta la Política de Privacidad de SerpApi para saber cómo SerpApi maneja búsquedas y cuentas.
• Conservado: mcp.serpapi.com registra métricas de solicitudes (método, código de estado, duración) y no almacena consultas ni resultados. Una clave en la ruta URL puede aparecer en los registros de solicitudes, por lo que se prefiere el encabezado.
• Paquete local: la extensión de Claude Desktop se ejecuta en tu máquina, mantiene la clave en la configuración de Claude Desktop y llama a serpapi.com directamente. Nada pasa a través de mcp.serpapi.com.
• Contacto: privacy@serpapi.com, o abre un issue.

Contribuciones

1. Haz un fork del repositorio
2. Crea tu rama de características: git checkout -b feature/amazing-feature
3. Instala las dependencias: uv install
4. Realiza tus cambios
5. Confirma los cambios: git commit -m 'Add amazing feature'
6. Envía a la rama: git push origin feature/amazing-feature
7. Abre una Solicitud de Extracción

Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.