MCP Web Search Tool

Herramienta de Búsqueda Web MCP

Un servidor MCP que brinda al asistente búsqueda web en vivo, lectura de páginas completas y citas de fuentes. Transporte Stdio, proveedores conectables, sin dependencias de scraping.

Inicio rápido · Herramientas · Configuración · Clientes · Seguridad · Registro de cambios

---

Descripción general

Cinco herramientas: web_search, news_search, image_search, fetch_url, list_providers. La búsqueda devuelve resúmenes clasificados con identificadores estables; fetch_url lee la página detrás de cualquier identificador. Brave Search es el proveedor principal; DuckDuckGo funciona sin clave como respaldo.

Requisitos

Node.js	>= 20.18 (usa fetch nativo)
npm	>= 10
Clave de API de Brave Search	opcional. Sin ella, DuckDuckGo maneja web_search. news_search y image_search requieren una clave.

Inicio rápido

git clone https://github.com/gabrimatic/mcp-web-search-tool.git
cd mcp-web-search-tool
npm install
cp .env.example .env   # edit BRAVE_API_KEY if you have one
npm run build
npm start

Ejecutar con Docker:

docker build -t mcp-web-search .
docker run --rm -i -e BRAVE_API_KEY mcp-web-search

Para integración con Claude Desktop, Claude Code, Codex, VS Code, Cursor o Windsurf, consulte MCP_CLIENTS.md.

---

Herramientas

Cada herramienta devuelve dos bloques de contenido: una representación en Markdown para el modelo y un bloque JSON delimitado con la carga estructurada. Los errores regresan como contenido isError: true con un mensaje accionable; solo las llamadas a herramientas desconocidas generan un error de protocolo.

web_search

Búsqueda web en vivo. Úsela primero para respuestas actuales respaldadas por fuentes.

Parámetro	Tipo	Descripción
search_term	cadena, obligatorio	Cadena de consulta.
provider	enumeración	"brave search" o "duckduckgo". Por defecto usa Brave cuando hay una clave configurada; de lo contrario, DuckDuckGo.
count	entero (1–20)	Número de resultados. Por defecto 10.
offset	entero	Desplazamiento de paginación (solo web).
cursor	cadena	Cursor opaco de una respuesta anterior.
freshness	cadena	pd (24 h), pw (semana), pm (mes), py (año) o YYYY-MM-DDtoYYYY-MM-DD.
country	cadena	Código de país ISO.
search_lang	cadena	Idioma de la interfaz, p. ej. en.
safesearch	enumeración	off, moderate, strict.
include_domains	cadena[]	Restringir resultados a estos hosts.
exclude_domains	cadena[]	Excluir resultados de estos hosts (coincidencia por sufijo de nombre de host).

news_search

Noticias recientes con nombre de la fuente y fecha de publicación. Solo Brave.

image_search

Resultados de imágenes con miniaturas. Solo Brave.

fetch_url

Lee un resultado de búsqueda o una URL http(s) arbitraria. Pase un identificador de resultado de una búsqueda anterior (preferido) o una URL completa.

Parámetro	Tipo	Descripción
id_or_url	cadena	Un identificador de resultado (p. ej. r_a1b2c3d4e5f6) o una URL http(s) completa.
url	cadena	Alias obsoleto para id_or_url.
max_chars	entero (200–200 000)	Límite suave de caracteres devueltos. Por defecto 8000.
cursor	cadena	Cursor de una respuesta anterior para continuar la lectura.

Devuelve el título de la página, el texto legible (se eliminan scripts, estilos, navegación, pie de página y apartados), los primeros 25 enlaces salientes, el estado HTTP, el tipo de contenido, la longitud en bytes y un nextCursor cuando se trunca.

Rechaza esquemas que no sean http(s) y cualquier host que resuelva a una dirección privada, de bucle local, de enlace local, multicast o IPv4 asignada a IPv6 privada. Detalles: SECURITY.md.

list_providers

Devuelve los proveedores registrados y el predeterminado actual. Llámela una vez si no está seguro de si news_search o image_search están disponibles en esta sesión.

---

Configuración

Toda la configuración se maneja mediante variables de entorno. Referencia: .env.example.

Variable	Predeterminado	Propósito
BRAVE_API_KEY	vacío	Clave de API de Brave Search. Cuando no está configurada, se usa DuckDuckGo.
MAX_RESULTS	10	Cantidad predeterminada de resultados (limitada a 1–50).
REQUEST_TIMEOUT	10000	Tiempo de espera por solicitud en ms (1 000–60 000).
DEFAULT_PROVIDER	auto	Forzar un proveedor específico (p. ej. duckduckgo).
ALLOW_KEYLESS	true	Cuando false, el servidor se niega a iniciar sin BRAVE_API_KEY.
CACHE_MAX_ENTRIES / CACHE_TTL_MS	256 / 300000	Caché de búsqueda.
FETCH_CACHE_MAX / FETCH_CACHE_TTL_MS	128 / 600000	Caché de obtención de URL.
FETCH_TIMEOUT_MS / FETCH_MAX_BYTES	15000 / 2000000	Presupuesto por solicitud para fetch_url.

---

Estructura del proyecto

src/
├── index.ts                    MCP server: tool registry, dispatch, rendering
├── config.ts                   env loader, validation, defaults
├── providers/
│   ├── SearchProvider.ts       abstract contract and shared types
│   ├── SearchProviderFactory   registry and default selection
│   ├── BraveSearchProvider     web/news/images via Brave API
│   └── DuckDuckGoProvider      keyless HTML-lite fallback
├── services/
│   ├── SearchService.ts        provider dispatch, LRU+TTL cache
│   └── FetchService.ts         safe URL fetch, readable extraction
└── utils/
    ├── http.ts                 native fetch, retry/backoff/timeout
    ├── html.ts                 zero-dep HTML to text + links
    ├── cache.ts                LRU+TTL cache
    └── ids.ts                  stable result-id minting and resolution
tests/                          vitest suite

Agregar un proveedor

import { SearchProvider, SearchResponse, SearchOptions } from './SearchProvider.js';

export class MyProvider extends SearchProvider {
  getName() { return 'My Provider'; }
  override requiresApiKey() { return true; }
  async search(query: string, _opts: SearchOptions = {}): Promise<SearchResponse> {
    const out = this.emptyResponse(query, 'web');
    out.results = mapped; // shape: SearchResult[]
    return out;
  }
}

Regístrelo en SearchProviderFactory.setupDefaults. Los identificadores de resultado se generan automáticamente cuando llama a mintResultId(url) en cada entrada.

---

Desarrollo

npm run dev          # tsx watch mode
npm test             # vitest (23 tests)
npm run lint
npm run format
npm run build

CI se ejecuta en Node 20, 22 y 24, además de una compilación de imagen Docker. Las pruebas cubren la caché LRU+TTL, el extractor de HTML, el analizador de DuckDuckGo, la caché del servicio de búsqueda, el reintento/retroceso HTTP, la protección SSRF, la coincidencia de dominio y el resolvedor de identificadores de resultado.

---

Ejemplos de indicaciones

• "¿Qué dicen los analistas sobre la carrera por el MVP después de los partidos de la NBA de esta noche?"
• "Resume los tres mejores resultados para RAG benchmarks 2025 y extrae el resumen del primer artículo."
• "Busca imágenes del último campo profundo del telescopio Webb, luego abre la página de la NASA y cita el pie de foto."
• "¿Cómo está el clima en Berlín ahora mismo?"

---

Licencia

Licencia MIT

Desarrollador

Por Soroush Yousefpour

© Todos los derechos reservados.

Video de YouTube

Una breve demostración de la Herramienta de Búsqueda Web MCP con Claude:

Claude + Búsqueda Web MCP – Demostración en vivo

Artículo en Medium

Antecedentes del proyecto y cómo funciona:

Análisis profundo de la Herramienta de Búsqueda Web MCP

Soporte