google-surf-mcp

✨MCP de búsqueda anti-bot: Sin clave API✨

Inglés | 한국어

Solo demostración. Las búsquedas reales se ejecutan sin interfaz gráfica (headless) por defecto (sin navegador visible). Establece SURF_HEADLESS=false para hacer que Chrome sea visible como en el clip de arriba.

MCP de búsqueda de Google. Sin clave API. Simplemente funciona.

• ✅ Realmente funciona (probé 6 MCPs de búsqueda de Google gratuitos, todos fallaron)

• ✅ Búsqueda + extracción de URL en un solo MCP (reemplaza la combinación habitual de MCP de búsqueda + MCP de extracción)

• ✅ 4 herramientas: search / search_parallel / extract / search_extract

• ✅ Sin clave API, sin proxies, sin solucionador

• ✅ Recuperación automática de CAPTCHA (se abre Chrome, un humano lo resuelve una vez, la llamada se reintenta)

• ✅ Protección SSRF en extract (bloquea localhost, IPs privadas, metadatos de AWS por defecto)

Qué es

Conéctalo a cualquier cliente MCP y obtendrás la búsqueda de Google como herramienta.

Sin solucionador de CAPTCHA. Cuando aparece un CAPTCHA en cualquier herramienta, se abre una ventana de Chrome para que un humano lo resuelva. Cada resolución preserva la reputación del perfil con Google. Creado para un uso sostenible y ético.

La instalación única requiere un calentamiento del perfil de ~1s (ver Instalación).

Diseñado para uso local. No es adecuado para despliegues sin estado / serverless.

Related MCP server: G-Search MCP

Números

Medido en una estación de trabajo con una conexión de 1Gb/s.

Stack

• Playwright + perfil de Chrome persistente

• playwright-extra stealth

• Imágenes / medios / fuentes bloqueados por recursos para mayor velocidad

• Arranque de perfil de una sola vez antes de la primera ejecución

• Mozilla Readability + Turndown para la extracción de artículos

Instalación

Requiere Node 18+ y Google Chrome (o Chromium) en el sistema.

npx google-surf-mcp   # actual MCP - register in client config

O clon local:

git clone https://github.com/HarimxChoi/google-surf-mcp
cd google-surf-mcp
npm install
npm run bootstrap

bootstrap abre una ventana de Chrome. Realiza una búsqueda en Google en ella. Cierra. El perfil ahora está caliente.

Sobrescribe las rutas si es necesario:

CHROME_PATH=/path/to/chrome SURF_TZ=America/New_York npm run bootstrap

Uso con Claude Code

Pega esto en tu ~/.claude.json:

{
  "mcpServers": {
    "google-surf": {
      "command": "npx",
      "args": ["-y", "google-surf-mcp"]
    }
  }
}

Reinicia Claude Code. Listo. search, search_parallel, extract, search_extract ya están disponibles.

Para otros clientes MCP, usa la misma estructura JSON en su archivo de configuración.

Variante de clon local:

{
  "mcpServers": {
    "google-surf": {
      "command": "node",
      "args": ["/abs/path/to/google-surf-mcp/build/index.js"]
    }
  }
}

Herramientas

• search(query, limit?) - consulta única, ~1.5s. Devuelve título / url / fragmento. Anuncios patrocinados filtrados.

• search_parallel(queries[], limit?) - pool de 4, máximo 10 consultas por llamada.

• extract(url, max_chars?) - obtiene una URL, devuelve el artículo en markdown (Readability con respaldo de texto). Los fallos devuelven { error }, nunca lanzan error.

• search_extract(query, limit?, max_chars?) - búsqueda + extracción paralela en una sola llamada. Devuelve resultados SERP enriquecidos con el contenido completo del artículo. Los fallos por página están aislados.

search_extract es la herramienta estrella: SERP + contenido completo del artículo en una sola llamada. Reemplaza la combinación habitual de "MCP de búsqueda + MCP de extracción de URL" que la mayoría de los agentes combinan.

Variables de entorno

Solución de problemas

• CAPTCHA: se abre automáticamente una ventana visible de Chrome (funciona para las 4 herramientas). Resuélvelo una vez, realiza una búsqueda dentro, la llamada se reintenta y continúa. Para fallar rápido en su lugar, ejecuta sin pantalla adjunta.

• "Chrome not found": instala Chrome o establece CHROME_PATH.

• Selectores obsoletos: Google rota las clases. Las PR son bienvenidas.

Registro de cambios

Ver CHANGELOG.md.

Licencia

MIT