Skip to main content
Glama
enesjakozh
hunter-arton

Google Search MCP Server

by hunter-arton
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Servidor MCP de Búsqueda de Google

Un servidor de Protocolo de Contexto de Modelo (MCP) que ofrece funciones de búsqueda web e imágenes a través de la API de Búsqueda Personalizada de Google. Este servidor cumple con la especificación MCP para integrarse con Claude y otros asistentes de IA.

Lo que estamos construyendo

Muchos asistentes de IA no tienen información actualizada ni la capacidad de buscar en la web. Este servidor MCP soluciona este problema proporcionando dos herramientas:

  • google_web_search : busca en la web información actualizada

  • google_image_search : Encuentra imágenes relacionadas con las consultas

Una vez conectado a un cliente compatible con MCP (como Claude in Cursor, VSCode o Claude Desktop), su asistente de IA puede realizar búsquedas y acceder a información actual.

Related MCP server: Google Search MCP Server

Conceptos básicos de MCP

Los servidores MCP proporcionan capacidades a los asistentes de IA. Este servidor implementa:

  • Herramientas : Funciones que la IA puede llamar (con la aprobación del usuario)

  • Comunicación estructurada : formato de mensajería estandarizado a través del protocolo MCP

  • Capa de transporte : comunicación a través de entrada/salida estándar

Prerrequisitos

  • Node.js (v18 o superior) y npm

  • Cuenta de Google Cloud Platform

  • Clave de API de búsqueda personalizada de Google e ID de motor de búsqueda

  • Un cliente compatible con MCP (Claude for Desktop, Cursor, VSCode con Claude, etc.)

Inicio rápido (Clonar este repositorio)

Si desea utilizar este servidor sin construirlo desde cero, siga estos pasos:

# Clone the repository
git clone https://github.com/yourusername/google-search-mcp-server.git
cd google-search-mcp-server

# Install dependencies
npm install

# Set up your environment variables
# Setup .env file in the root folder of the project

# On macOS/Linux
touch .env

# On Windows
new-item .env

# Edit .env file to add your Google API credentials
# Use any text editor you prefer (VS Code, Notepad, nano, vim, etc.)
# Add these to your newly created .env

GOOGLE_API_KEY=your_api_key_here
GOOGLE_CSE_ID=your_search_engine_id_here

# Build the server
npm run build

# Test the server (optional)
# On macOS/Linux
echo '{"jsonrpc":"2.0","method":"listTools","id":1}' | node dist/index.js

# On Windows PowerShell
echo '{"jsonrpc":"2.0","method":"listTools","id":1}' | node dist/index.js

# On Windows CMD
echo {"jsonrpc":"2.0","method":"listTools","id":1} | node dist/index.js

Después de la construcción, siga la sección Conexión a clientes MCP para conectar el servidor a su cliente preferido.

Configura tu entorno (construye desde cero)

Si prefieres construir el servidor tú mismo desde cero, sigue estas instrucciones:

Crear la estructura del proyecto

macOS/Linux

# Create a new directory for our project
mkdir google-search-mcp
cd google-search-mcp

# Initialize a new npm project
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk dotenv zod
npm install -D @types/node typescript

# Create our files
mkdir src
touch src/index.ts

Ventanas

# Create a new directory for our project
md google-search-mcp
cd google-search-mcp

# Initialize a new npm project
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk dotenv zod
npm install -D @types/node typescript

# Create our files
md src
new-item src\index.ts

Configurar TypeScript

Cree un tsconfig.json en el directorio raíz:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Actualizar package.json

Asegúrese de que su package.json incluya:

{
  "name": "google_search_mcp",
  "version": "0.1.0",
  "description": "MCP server for Google Custom Search API integration",
  "license": "MIT",
  "type": "module",
  "bin": {
    "google_search": "./dist/index.js"
  },
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "tsc",
    "build:unix": "tsc && chmod 755 dist/index.js",
    "prepare": "npm run build",
    "watch": "tsc --watch",
    "start": "node dist/index.js"
  }
}

Configuración de la API de Google

Necesitará configurar Google Cloud Platform y obtener las credenciales de API:

Configuración de Google Cloud Platform

  1. Ir a la consola de Google Cloud

  2. Crear un nuevo proyecto

  3. Habilitar la API de búsqueda personalizada:

    Navigate to "APIs & Services" → "Library"
Search for "Custom Search API"
Click on "Custom Search API" → "Enable"

  4. Crear credenciales de API:

    Navigate to "APIs & Services" → "Credentials"
Click "Create Credentials" → "API key"
Copy your API key

Configuración de motor de búsqueda personalizado

  1. Ir al motor de búsqueda programable

  2. Haga clic en "Agregar" para crear un nuevo motor de búsqueda.

  3. Seleccione "Buscar en toda la web" y nombre su motor de búsqueda.

  4. Obtenga su ID de motor de búsqueda (valor cx) desde el Panel de control

Configuración del entorno

Cree un archivo .env en el directorio raíz:

GOOGLE_API_KEY=your_api_key_here
GOOGLE_CSE_ID=your_search_engine_id_here

Agregue .env a su archivo .gitignore para proteger sus credenciales:

echo ".env" >> .gitignore

Construyendo su servidor

Crear la implementación del servidor

Cree la implementación de su servidor en src/index.ts :

import dotenv from "dotenv"
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  Tool,
} from "@modelcontextprotocol/sdk/types.js";

dotenv.config();

// Define your tools
const WEB_SEARCH_TOOL: Tool = {
  name: "google_web_search",
  description: "Performs a web search using Google's Custom Search API...",
  inputSchema: {
    // Schema details here
  },
};

const IMAGE_SEARCH_TOOL: Tool = {
  name: "google_image_search",
  description: "Searches for images using Google's Custom Search API...",
  inputSchema: {
    // Schema details here
  }
};

// Server implementation
const server = new Server(
  {
    name: "google-search",
    version: "0.1.0",
  },
  {
    capabilities: {
      tools: {},
    },
  },
);

// Check for API key and Search Engine ID
const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY!;
const GOOGLE_CSE_ID = process.env.GOOGLE_CSE_ID!;

if (!GOOGLE_API_KEY || !GOOGLE_CSE_ID) {
  console.error("Error: Missing environment variables");
  process.exit(1);
}

// Tool handlers
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [WEB_SEARCH_TOOL, IMAGE_SEARCH_TOOL],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  // Implement tool handlers
});

// Run the server
async function runServer() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Google Search MCP Server running on stdio");
}

runServer().catch((error) => {
  console.error("Fatal error running server:", error);
  process.exit(1);
});

Para obtener los detalles completos de implementación, consulte los archivos del repositorio.

Construyendo el servidor

Después de completar su implementación, construya el servidor:

npm run build

Esto compilará el código TypeScript a JavaScript en el directorio dist .

Conexión a clientes MCP

Los servidores MCP se pueden conectar a varios clientes. Aquí tienes las instrucciones de configuración para los más populares:

Claude para escritorio

macOS/Linux

  1. Abra su archivo de configuración:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

  1. Agregue la configuración del servidor:

{
  "mcpServers": {
    "google_search": {
      "command": "node",
      "args": [
        "/absolute/path/to/google-search-mcp/dist/index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

Ventanas

  1. Abra su archivo de configuración:

code $env:AppData\Claude\claude_desktop_config.json

  1. Agregue la configuración del servidor:

{
  "mcpServers": {
    "google_search": {
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\google-search-mcp\\dist\\index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

  1. Reiniciar Claude para escritorio

  2. Verifique que las herramientas aparezcan haciendo clic en el ícono de la herramienta en la interfaz

VSCode con Claude

macOS/Linux y Windows

  1. Instalar la extensión MCP para VSCode

  2. Cree o edite .vscode/settings.json en su espacio de trabajo:

Para macOS/Linux:

{
  "mcp.servers": {
    "google_search": {
      "command": "node",
      "args": [
        "/absolute/path/to/google-search-mcp/dist/index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

Para Windows:

{
  "mcp.servers": {
    "google_search": {
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\google-search-mcp\\dist\\index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

  1. Reiniciar VSCode

  2. Las herramientas estarán disponibles para Claude en VSCode

Cursor

  1. Abrir la configuración del cursor (icono de engranaje)

  2. Busque "MCP" y abra la configuración de MCP

  3. Haga clic en "Agregar nuevo servidor MCP"

  4. Configurar con configuraciones similares a las anteriores:

Para macOS/Linux:

{
  "mcpServers": {
    "google_search": {
      "command": "node",
      "args": [
        "/absolute/path/to/google-search-mcp/dist/index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

Para Windows:

{
  "mcpServers": {
    "google_search": {
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\google-search-mcp\\dist\\index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

  1. Reiniciar cursor

Probando su servidor

Usando con Claude

Una vez conectado, puedes probar las herramientas haciéndole a Claude preguntas como:

  • Busca las últimas noticias sobre energías renovables.

  • "Encuentra imágenes de vehículos eléctricos"

  • "¿Cuáles son los principales destinos turísticos en Japón?"

Claude utilizará automáticamente la herramienta de búsqueda adecuada cuando sea necesario.

Pruebas manuales

También puedes probar tu servidor directamente:

# Test web search
echo '{
  "jsonrpc": "2.0",
  "method": "callTool",
  "params": {
    "name": "google_web_search",
    "arguments": {
      "query": "test query",
      "count": 2
    }
  },
  "id": 1
}' | node dist/index.js

¿Qué está pasando bajo el capó?

Cuando haces una pregunta:

  1. El cliente envía su pregunta a Claude

  2. Claude analiza las herramientas disponibles y decide cuál utilizar

  3. El cliente ejecuta la herramienta elegida a través de su servidor MCP

  4. Los resultados se envían a Claude.

  5. Claude formula una respuesta en lenguaje natural basada en los resultados de la búsqueda.

  6. La respuesta se te muestra

Solución de problemas

Problemas comunes

Variables de entorno

Si ve Error: GOOGLE_API_KEY environment variable is required :

# Check your .env file
cat .env

# Try setting environment variables directly:
export GOOGLE_API_KEY=your_key_here
export GOOGLE_CSE_ID=your_id_here

Errores de API

Si encuentra errores de API:

# Test your API credentials directly
curl "https://www.googleapis.com/customsearch/v1?key=YOUR_API_KEY&cx=YOUR_CX_ID&q=test"

Problemas de conexión

Si su cliente no puede conectarse al servidor:

# Verify the server runs correctly on its own
node dist/index.js

# Check file permissions
chmod 755 dist/index.js

# Ensure you're using absolute paths in your configuration

Referencia de API

google_web_search

Realiza una búsqueda web utilizando la API de búsqueda personalizada de Google.

Parámetros:

  • query (cadena, obligatoria): La consulta de búsqueda

  • count (número, opcional): Número de resultados (1-10, predeterminado 5)

  • start (número, opcional): Índice de inicio de paginación (predeterminado 1)

  • site (cadena, opcional): limita la búsqueda a un sitio específico (por ejemplo, 'ejemplo.com')

google_image_search

Busca imágenes utilizando la API de búsqueda personalizada de Google.

Parámetros:

  • query (cadena, obligatoria): La consulta de búsqueda de imágenes

  • count (número, opcional): Número de resultados (1-10, predeterminado 5)

  • start (número, opcional): Índice de inicio de paginación (predeterminado 1)

Limitaciones

  • Nivel gratuito de la API de búsqueda personalizada de Google: 100 consultas por día

  • Límite de velocidad impuesto por el servidor: 5 solicitudes por segundo

  • Máximo 10 resultados por consulta (limitación de la API de Google)

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Available Tools

2 tools

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.0
    • First observedgoogle_image_search
    • First observedgoogle_web_search
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: google_image_search is for finding images, while google_web_search is for general web content like articles and news. There is no overlap in functionality, making it easy for an agent to choose the correct tool based on the need for visual vs. textual information.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern with 'google_' prefix and descriptive suffixes (_image_search, _web_search). The naming is uniform and predictable, adhering to snake_case throughout without any deviations or mixed conventions.

Tool Count4/5

With only 2 tools, the server is minimal but reasonable for a search-focused domain, covering image and web searches. It might feel slightly thin if broader search capabilities (e.g., video, news-specific) were expected, but it's well-scoped for basic search needs without being overloaded.

Completeness4/5

For a Google Search server, the tools cover the core search operations: image and web searches. Minor gaps exist, such as lack of specialized search types (e.g., video, scholarly articles) or advanced filtering options, but agents can work around this with the provided tools for most common queries.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches