mcp-google-custom-search

Google Custom Search MCP

Español | Русский

A1 Google Custom Search MCP permite que una aplicación de IA busque en la web e imágenes en lenguaje natural a través de tu Motor de Búsqueda Programable. Pide páginas, filtra por idioma, país, fecha o sitio, navega por los resultados y obtén archivos de imagen con miniaturas.

Utiliza la API JSON de Google Custom Search con tu clave de API de Google Cloud. Tú decides qué cubre el motor — un puñado de sitios o toda la web — y el servidor hace explícitos los límites de la API JSON en lugar de dar a entender que cada tarea de búsqueda es posible.

• 3 herramientas. Búsqueda web, búsqueda de imágenes y una vía de escape GET sin procesar para parámetros que las herramientas tipadas no exponen.
• Solo lectura de principio a fin. La API JSON de Custom Search no tiene endpoint de escritura; cada herramienta está marcada como de solo lectura y nada aquí puede modificar datos.
• Tú controlas la cobertura. La configuración del motor decide qué se busca; los resultados y el ranking pueden diferir de google.com.
• La clave permanece en un encabezado. Autenticación mediante clave de API — sin OAuth, sin ámbitos; la clave viaja en el encabezado X-Goog-Api-Key y nunca aparece en una URL.
• No es Google Search Console. No puede informar cómo está indexado o clasificado tu propio sitio.

Comienza con una pregunta de solo lectura:

Encuentra artículos recientes sobre la adopción de passkeys del último mes y resume los tres mejores resultados.

Conecta el servidor · Explora casos de uso · Abre la documentación técnica

Véelo funcionar en un minuto

Tú: Encuentra artículos recientes sobre la adopción de passkeys, solo en inglés, del último mes.

Asistente: Ejecuta una búsqueda a través de tu motor y muestra el título, enlace y fragmento de cada resultado. Nada cambia — cada herramienta es de solo lectura.

Tú: Muestra la siguiente página.

Asistente: Continúa desde el cursor next_start y muestra los resultados 11–20 de la misma consulta.

Tú: Ahora encuentra fotos de prensa grandes sobre el mismo tema.

Asistente: Cambia a búsqueda de imágenes y devuelve archivos de imagen con sus dimensiones, miniaturas y las páginas que los alojan.

Contenido

• Inicio rápido
• Qué puedes pedirle que haga
• Cómo funciona una búsqueda
• Qué puede cambiar
• Cómo obtener acceso
• Configuración
• Datos, límites y trabajo en segundo plano
• Documentación técnica
• Soporte

Inicio rápido

Necesitas Node.js 20+, una clave de API de Google Cloud con la API de Custom Search habilitada y un ID de Motor de Búsqueda Programable (cx).

1. Obtén una clave de API y un ID de motor.
2. Añade el servidor a tu aplicación de IA.
3. Haz la pregunta de solo lectura anterior.

codex mcp add google-custom-search \
  --env GOOGLE_CUSTOM_SEARCH_API_KEY=your_api_key \
  --env GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your_engine_id \
  -- npx -y mcp-google-custom-search@latest

codex mcp list

claude mcp add \
  --env GOOGLE_CUSTOM_SEARCH_API_KEY=your_api_key \
  --env GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your_engine_id \
  --transport stdio --scope user google-custom-search \
  -- npx -y mcp-google-custom-search@latest

claude mcp list

{
  "mcpServers": {
    "google-custom-search": {
      "command": "npx",
      "args": ["-y", "mcp-google-custom-search@latest"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "your_api_key",
        "GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "your_engine_id"
      }
    }
  }
}

{
  "mcpServers": {
    "google-custom-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-custom-search@latest"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "your_api_key",
        "GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "your_engine_id"
      }
    }
  }
}

{
  "servers": {
    "google-custom-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-custom-search@latest"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "${input:custom_search_api_key}",
        "GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "${input:custom_search_engine_id}"
      }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "custom_search_api_key", "description": "Google Cloud API key", "password": true },
    { "type": "promptString", "id": "custom_search_engine_id", "description": "Programmable Search Engine id (cx)" }
  ]
}

Qué puedes pedirle que haga

Buscar en la web

• Encuentra tutoriales recientes sobre un tema y resume los mejores resultados.
• Busca solo dentro de docs.python.org — o en todas partes excepto en un sitio que no te inspire confianza.
• Muestra la siguiente página de resultados para la misma consulta.

Acotar los resultados

• Solo páginas en inglés publicadas en el último mes.
• Solo archivos PDF; exige una frase exacta o excluye un término.
• Restringe al contenido de un país, o a material con derechos de uso específicos.

Encontrar imágenes

• Encuentra fotos grandes sobre un tema, con dimensiones y miniaturas.
• Solo clipart o dibujos lineales, en blanco y negro.
• Muestra la página de la que proviene cada imagen.

Ir más allá de las herramientas tipadas

• Llama a la API con parámetros que las herramientas tipadas no exponen — fields para recortar la respuesta, lowRange/highRange, hq.
• Obtén el sobre de respuesta sin procesar con promociones y el pagemap completo.

Cómo funciona una búsqueda

1. Cada consulta se ejecuta a través de un Motor de Búsqueda Programable, identificado por su ID cx — el predeterminado configurado o un engine_id por llamada. La configuración del motor decide la cobertura: una lista de sitios específicos, o toda la web cuando "Buscar en toda la web" está habilitado.
2. Los resultados vuelven normalizados — título, URL, fragmento y metadatos — con cursores next_start/previous_start para paginar. total_results es la estimación de Google y puede reducirse al paginar.
3. La API devuelve como máximo 10 resultados por llamada y 100 por consulta (start + num - 1 debe ser ≤ 100). El servidor rechaza una ventana más amplia antes de la solicitud — la API respondería 400 después de gastar una unidad de cuota.
4. La búsqueda de imágenes requiere que Image search esté habilitado en el panel de control del motor; de lo contrario, la API responde 400.

Un corrected_query en la respuesta es solo una sugerencia ortográfica — los resultados siguen siendo para la consulta original. Y esto es Búsqueda Programable, no Google Search Console: la API no puede informar cómo está indexado o clasificado tu propio sitio.

Qué puede cambiar

Cada herramienta lleva la anotación de solo lectura, incluida la vía de escape. La API JSON de Custom Search es un único endpoint GET sin escrituras, por lo que lo único que gasta una llamada es una unidad de tu cuota diaria.

Cómo obtener acceso

Google Custom Search autentica con una clave de API; no intervienen OAuth ni ámbitos.

1. Crea o selecciona un proyecto de Google Cloud y habilita la API de Custom Search.
2. Crea una clave de API en APIs y servicios → Credenciales. Restringir la clave a la API de Custom Search es un buen hábito.
3. Crea un Motor de Búsqueda Programable en el panel de control y copia su ID de motor de búsqueda (cx). Habilita Buscar en toda la web para búsqueda abierta y Búsqueda de imágenes para la herramienta de imágenes.

Trata la clave de API como una contraseña. El servidor la envía en el encabezado X-Goog-Api-Key, nunca en una URL, por lo que las URLs registradas o reflejadas no pueden filtrarla.

Configuración

Sin credenciales, el servidor aún se inicia y completa el protocolo de enlace MCP; la primera llamada a una herramienta explica exactamente qué variables configurar. La única configuración mal formada es un ID de motor sin clave de API — la clave no se puede proporcionar por llamada, por lo que ambas deben establecerse juntas.

Datos, límites y trabajo en segundo plano

• Las solicitudes van a Google. El servidor local llama a la API JSON de Custom Search. Su telemetría anónima contiene un ID de instalación, versión del paquete, cliente de IA y versiones de plataforma, y nombres de herramientas — nunca la clave de API, consultas de búsqueda, resultados o argumentos de herramientas. Establece ASKADS_TELEMETRY=0 para optar por no participar.
• Google aplica una cuota diaria. Cada llamada de cualquiera de las tres herramientas cuesta una unidad de la cuota por proyecto — 100 consultas por día gratis, hasta 10,000 por día con facturación. En 429, el servidor retrocede respetando Retry-After; como toda la API consiste en GETs idempotentes, 5xx y los errores de red también se reintentan, mientras que 400/403 fallan rápidamente.
• No hay sondeo en segundo plano. El servidor solo se ejecuta cuando se le llama. Si tu aplicación de IA admite tareas programadas, puede volver a ejecutar una búsqueda periódicamente — cada ejecución sigue gastando unidades de cuota.

Documentación técnica

• Catálogo de capacidades MCP — páginas orientadas a tareas para cada herramienta.
• Todas las herramientas y entradas
• Documentación de desarrollo
• Documentación de publicación
• Referencia de la API JSON de Custom Search

Soporte

¿Encontraste un error o necesitas un escenario? Crea un issue o escribe en Telegram.

¡Llegaste al final!