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.

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

Ir a la consola de Google Cloud
Crear un nuevo proyecto
Habilitar la API de búsqueda personalizada:
Navigate to "APIs & Services" → "Library" Search for "Custom Search API" Click on "Custom Search API" → "Enable"
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

Ir al motor de búsqueda programable
Haga clic en "Agregar" para crear un nuevo motor de búsqueda.
Seleccione "Buscar en toda la web" y nombre su motor de búsqueda.
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

Abra su archivo de configuración:

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

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

Abra su archivo de configuración:

code $env:AppData\Claude\claude_desktop_config.json

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"
      }
    }
  }
}

Reiniciar Claude para escritorio
Verifique que las herramientas aparezcan haciendo clic en el ícono de la herramienta en la interfaz

VSCode con Claude

macOS/Linux y Windows

Instalar la extensión MCP para VSCode
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"
      }
    }
  }
}

Reiniciar VSCode
Las herramientas estarán disponibles para Claude en VSCode

Cursor

Abrir la configuración del cursor (icono de engranaje)
Busque "MCP" y abra la configuración de MCP
Haga clic en "Agregar nuevo servidor MCP"
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"
      }
    }
  }
}

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:

El cliente envía su pregunta a Claude
Claude analiza las herramientas disponibles y decide cuál utilizar
El cliente ejecuta la herramienta elegida a través de su servidor MCP
Los resultados se envían a Claude.
Claude formula una respuesta en lenguaje natural basada en los resultados de la búsqueda.
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.

Servidor MCP de Búsqueda de Google

Lo que estamos construyendo

Conceptos básicos de MCP

Prerrequisitos

Inicio rápido (Clonar este repositorio)

Configura tu entorno (construye desde cero)

Crear la estructura del proyecto

macOS/Linux

Ventanas

Configurar TypeScript

Actualizar package.json

Configuración de la API de Google

Configuración de Google Cloud Platform

Configuración de motor de búsqueda personalizado

Configuración del entorno

Construyendo su servidor

Crear la implementación del servidor

Construyendo el servidor

Conexión a clientes MCP

Claude para escritorio

macOS/Linux

Ventanas

VSCode con Claude

macOS/Linux y Windows

Cursor

Probando su servidor

Usando con Claude

Pruebas manuales

¿Qué está pasando bajo el capó?

Solución de problemas

Problemas comunes

Variables de entorno

Errores de API

Problemas de conexión

Referencia de API

google_web_search

google_image_search

Limitaciones

Licencia

Appeared in Searches

`google_web_search`

`google_image_search`