Google Search MCP

Un servidor ligero del Protocolo de Contexto de Modelo (MCP) que permite a los modelos de IA buscar en la web mediante la API de Búsqueda Personalizada de Google.

GitHub
1

Documentación

Node.js TypeScript MCP Google Custom Search License

Listed on mcpservers.org

🔍 Un servidor MCP que permite a cualquier cliente de IA compatible con MCP buscar en la web en vivo a través de la API JSON de Búsqueda Personalizada de Google — a través de stdio, plug-and-play.

🧭 Tabla de Contenidos

✨ Descripción General

Este servidor cierra la brecha entre agentes de IA y conocimiento web en tiempo real. Habla el Protocolo de Contexto de Modelo (MCP) a través de stdio, por lo que cualquier cliente compatible puede llamar a una sola herramienta — search_google — y recibir resultados de búsqueda limpios y estructurados directamente desde Google.

┌─────────────────┐        stdio (MCP)        ┌──────────────────────┐        HTTPS        ┌───────────────────┐
│   MCP Client     │ ───────────────────────▶ │  Google Search MCP    │ ──────────────────▶ │  Google Custom     │
│ (Claude, etc.)   │ ◀─────────────────────── │       Server           │ ◀────────────────── │  Search JSON API   │
└─────────────────┘        results            └──────────────────────┘       results        └───────────────────┘

⚙️ Requisitos

RequisitoDetalles
🟢 Node.jsv18 o superior
🔑 Clave de API de GoogleCon acceso a la API JSON de Búsqueda Personalizada
🆔 ID del Motor de BúsquedaDe un Motor de Búsqueda Programable de Google (cx)

🔧 Configuración de Búsqueda Personalizada de Google

  1. Crea un proyecto en la Consola de Google Cloud
  2. Habilita la Custom Search API para ese proyecto
  3. Genera una clave de API
  4. Crea un Motor de Búsqueda Programable y copia su ID del Motor de Búsqueda

⚠️ Límites de Tasa y Cuota

El nivel gratuito de la API JSON de Búsqueda Personalizada de Google permite 100 consultas por día. Una vez alcanzado ese límite, la API devuelve un error 429 y search_google responderá con un mensaje de error en lugar de resultados.

  • ¿Necesitas más? Puedes habilitar la facturación en tu proyecto de Google Cloud para hasta 10,000 consultas/día (de pago, con precio por consulta).
  • Consulta tu uso actual en la Consola de Google Cloud en APIs y Servicios → API de Búsqueda Personalizada → Cuotas.

📦 Instalación

npm install

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

GOOGLE_API_KEY=your_google_api_key
SEARCH_ENGINE_ID=your_search_engine_id

⚠️

Nunca hagas commit de .env ni expongas tu clave de API en el control de versiones.

▶️ Ejecutar

Desarrollo (ejecutar TypeScript directamente):

npm start

Producción (compilar y luego ejecutar la salida compilada):

npm run build
node build/index.js

ℹ️ El servidor registra estados y errores en stderr, manteniendo stdout limpio para los mensajes del protocolo MCP.

🐳 Ejecutar con Docker

¿Prefieres contenedores? Puedes compilar y ejecutar este servidor sin instalar Node.js localmente.

Compilar la imagen:

docker build -t google-search-mcp .

Ejecutarlo (asegúrate de que tu archivo .env esté configurado primero — consulta Instalación):

docker run -i --rm --env-file .env google-search-mcp

⚠️

La bandera -i es obligatoria — este es un servidor MCP basado en stdio y necesita un flujo interactivo para comunicarse con el cliente.

O usa Docker Compose:

services:
  google-search-mcp:
    build: .
    stdin_open: true
    tty: true
    env_file:
      - .env

docker compose up --build

Apuntar tu cliente MCP a Docker

{
  "mcpServers": {
    "google-search": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", ".env", "google-search-mcp"]
    }
  }
}

🔌 Configuración del Cliente MCP

Después de compilar el proyecto, registra el servidor con un cliente compatible con MCP usando el punto de entrada compilado:

{
  "mcpServers": {
    "google-search": {
      "command": "node",
      "args": ["/absolute/path/to/Google-Search-MCP/build/index.js"],
      "env": {
        "GOOGLE_API_KEY": "your_google_api_key",
        "SEARCH_ENGINE_ID": "your_search_engine_id"
      }
    }
  }
}

O mantén las credenciales en el .env del proyecto y ejecuta desde el directorio del proyecto:

{
  "mcpServers": {
    "google-search": {
      "command": "node",
      "args": ["/absolute/path/to/Google-Search-MCP/build/index.js"]
    }
  }
}

🧩 Usar Este Servidor en Tu Propio Proyecto

Este servidor no está vinculado a un solo cliente — cualquier host compatible con MCP puede iniciarlo y llamar a search_google. Para usarlo en otro lugar:

  1. Clona y compila este repositorio (o descarga la imagen de Docker — consulta Ejecutar con Docker).
  2. Apunta la configuración de tu cliente MCP al punto de entrada compilado (build/index.js) o al comando de Docker, usando el mismo JSON que se muestra en Configuración del Cliente MCP.
  3. Clientes compatibles — cualquier herramienta que hable MCP a través de stdio funciona, incluyendo:
    • Claude Desktop
      • Cursor (.cursor/mcp.json)
      • Cline (configuración de la extensión de VS Code)
      • Agentes personalizados construidos directamente con el SDK de MCP
  4. Llamarlo programáticamente — si estás construyendo tu propio cliente/agente MCP en código, conecta un Client de MCP a través de StdioClientTransport apuntando a build/index.js, luego llama a la herramienta search_google como cualquier otra herramienta MCP. Consulta la documentación del SDK de TypeScript de MCP para ejemplos del lado del cliente.

Cada cliente tiene su propia ubicación y formato de archivo de configuración para mcpServers — consulta la documentación de ese cliente para saber exactamente dónde pegar el bloque JSON.

🛠️ Herramienta Disponible

search_google

Busca en la Búsqueda Personalizada de Google la consulta proporcionada y devuelve los 3 mejores resultados.

Entrada

{
  "query": "latest TypeScript release"
}

Salida

Cada resultado incluye:

  • 📌 title
  • 🔗 link
  • 📝 snippet

Si no se encuentra nada, la herramienta responde con No results found.

🧪 Probar con MCP Inspector

npm run build
npx @modelcontextprotocol/inspector node build/index.js

Asegúrate de que tus variables de entorno estén configuradas antes de lanzar el inspector.

📁 Estructura del Proyecto

📦 Google-Search-MCP
├── 📂 src
│   └── index.ts     # MCP server implementation
├── 📂 build          # Compiled JavaScript and type declarations
├── .env              # Local environment config (not committed)
└── README.md

🤝 Contribuciones

¡Las contribuciones, informes de errores y solicitudes de funciones son bienvenidas!

  • ¿Encontraste un error o tienes una idea? Abre un issue describiéndolo.
  • ¿Quieres contribuir con código?
    1. Haz un fork del repositorio 2. Crea una rama (git checkout -b feature/your-feature) 3. Haz tus cambios y prueba localmente (npm start o docker compose up --build) 4. Haz commit y push, luego abre un Pull Request

Por favor, mantén los PR enfocados — una función o corrección por PR facilita la revisión.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT.

Listed on mcpservers.org