Web Research MCP

Un servidor MCP de investigación web de alta calidad y múltiples fuentes para agentes de IA. Conéctalo a Claude Desktop, Hermes, Cursor o cualquier cliente compatible con MCP y obtén búsquedas de nivel de producción y recuperación de páginas en Wikipedia, arXiv, Hacker News, Stack Exchange, Crossref, Brave, Tavily y cualquier URL de la web.

# One-line install (anywhere on disk)
git clone https://github.com/infinit3labs/web-research-mcp.git
hermes mcp add web-research --command "$(pwd)/web-research-mcp/bin/web-research-mcp"
# 6 of 7 tools work with zero API keys. Add Brave or Tavily to unlock general web search.

Por qué existe esto

La mayoría de los servidores MCP de "búsqueda web" intentan hacer scraping de Google mediante un navegador headless con huellas digitales aleatorias. Ese enfoque es una carrera armamentista perdida: los motores de búsqueda detectan y bloquean a los scrapers en cuestión de días, e incluso cuando funciona, obtienes una sopa de DOM que tu LLM tiene que limpiar.

Este servidor adopta un enfoque diferente: habla con APIs que están diseñadas para agentes:

Las siete fuentes funcionan sin ninguna clave de API. Añadir una clave de Brave o Tavily desbloquea la búsqueda web general en tiempo real. Ese es el enfoque de mayor calidad: obtienes mejores resultados que con scraping porque las APIs de índices web reales usan señales (modelos de clic, frescura, análisis de enlaces) que ningún scraper puede replicar.

Inicio rápido

Opción A — pip install (cuando se publique)

pip install web-research-mcp
hermes mcp add web-research --command "$(which web-research-mcp)"

Opción B — Clonar desde el código fuente

git clone https://github.com/infinit3labs/web-research-mcp.git
hermes mcp add web-research \
  --command "$(pwd)/bin/web-research-mcp"

Cuando se te solicite, acepta las 7 herramientas. Listo.

Opción C — Instalar con Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "web-research": {
      "command": "/Users/code/mcp-servers/web-research/bin/web-research-mcp"
    }
  }
}

Opción D — Instalar con Cursor / cualquier cliente MCP stdio

{
  "mcpServers": {
    "web-research": {
      "command": "/absolute/path/to/web-research-mcp/bin/web-research-mcp"
    }
  }
}

El script de lanzamiento crea automáticamente un venv en la primera ejecución, instala las dependencias desde pyproject.toml y carga web-research.env para cualquier clave de API que hayas configurado.

2. (Opcional) Añade claves de API para la búsqueda web real

cp web-research.env.example web-research.env
$EDITOR web-research.env

El lanzador recoge las claves de web-research.env en cada invocación: no necesitas reiniciar tu cliente MCP.

3. Úsalo

Pregunta a tu agente cosas como:

"Busca en Hacker News y Stack Overflow los mejores servidores MCP publicados en 2026"

"Usa pro_mode para investigar el estado actual de los modelos de lenguaje pequeños"

"Recupera https://arxiv.org/abs/2506.06962 y resume la metodología"

"Contrasta esta afirmación con Wikipedia y arXiv"

Herramientas

Las 7 herramientas registradas en tools/list:

search_web — búsqueda web general de múltiples fuentes

search_web(
    query: str,                  # search query
    max_results: int = 10,       # per source, before dedup (1–30)
    pro_mode: bool = False,      # also fetch top 3 URLs and append excerpts
) -> str

Respaldada por Brave + Tavily con deduplicación por canonicalización de URL y refuerzo de puntuación entre fuentes. Requiere BRAVE_API_KEY y/o TAVILY_API_KEY. Sin claves, devuelve un mensaje claro que te indica cómo activarla.

pro_mode: true es la función estrella para investigación: ejecuta una búsqueda normal, recupera los 3 primeros resultados mediante Jina y añade el contenido como fragmento. Una sola llamada hace lo que de otro modo serían search_web + 3 × fetch_url.

fetch_url — markdown limpio de cualquier página

fetch_url(url: str) -> str

Pasa por Jina Reader, que:

• renderiza páginas con mucho JS (SPAs, aplicaciones React)

• evita la mayoría de la detección de bots (Jina está en lista blanca)

• devuelve markdown limpio con un bloque de metadatos (Title:, URL Source:, Published Time:)

• trunca a ~20k caracteres para proteger tu ventana de contexto

search_wikipedia — fundamentación enciclopédica

search_wikipedia(query: str, max_results: int = 5) -> str

Wikipedia MediaWiki API. Sin clave. Rápida. Ideal para definiciones y contexto histórico.

search_academic — preprints de arXiv

search_academic(query: str, max_results: int = 5) -> str

Devuelve título, autores, fragmento del resumen, fecha de publicación y URL del PDF. Sin clave. Ideal para informática, física, matemáticas y biología.

search_news — señal de Hacker News

search_news(query: str, max_results: int = 10) -> str

Devuelve título, URL, puntos, comentarios y fecha. Sin clave. Ideal para saber qué está de moda en tecnología ahora mismo.

search_stackexchange — preguntas y respuestas de más de 180 sitios

search_stackexchange(query: str, max_results: int = 5, site: str = "stackoverflow") -> str

Establece site en cualquier comunidad de SE: serverfault, superuser, askubuntu, math, tex, datascience, ai, etc. Sin clave.

search_scholar_meta — artículos revisados por pares mediante Crossref

search_scholar_meta(query: str, max_results: int = 5) -> str

Devuelve título, DOI, número de citas, editorial, fecha de publicación y resumen. Cubre artículos que arXiv no cubre (Elsevier, Springer, Wiley, IEEE, ACM). Sin clave.

Arquitectura

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                            │
│  (Claude Desktop, Hermes, Cursor, custom agent)          │
└────────────────────┬────────────────────────────────────┘
                     │ JSON-RPC over stdio
                     ▼
┌─────────────────────────────────────────────────────────┐
│              bin/web-research-mcp                         │
│  • Boots venv (or reuses cached one)                     │
│  • Sources web-research.env for API keys                 │
│  • Execs python -m web_research.server                   │
└────────────────────┬────────────────────────────────────┘
                     ▼
┌─────────────────────────────────────────────────────────┐
│           web_research.server (MCPServer)                 │
│  7 tool functions registered via @app.tool() decorator    │
│  • Pydantic-driven JSON schemas from type hints           │
│  • Single shared httpx.AsyncClient per call              │
│  • Graceful degradation: one bad source ≠ failed call    │
└────────────────────┬────────────────────────────────────┘
                     │ asyncio.gather for parallel fan-out
                     ▼
┌─────────────────────────────────────────────────────────┐
│          web_research.providers (7 backends)              │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐               │
│  │ brave    │ │ tavily   │ │ jina_fetch  │  ← general web│
│  └──────────┘ └──────────┘ └─────────────┘               │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐               │
│  │ wikipedia│ │ arxiv    │ │ crossref    │  ← academic   │
│  └──────────┘ └──────────┘ └─────────────┘               │
│  ┌──────────┐ ┌──────────┐                                │
│  │ hn_algolia│ │stackex   │  ← tech signal               │
│  └──────────┘ └──────────┘                                │
│  + merge_results() with URL-canonical dedup               │
└─────────────────────────────────────────────────────────┘

Decisiones de diseño clave

Primero las APIs, no el scraping. Esta es la tesis central. Cada fuente es una API oficial diseñada para acceso programático. Obtienes datos estructurados limpios, sin bloqueos de IP, sin carga de mantenimiento cuando los sitios rediseñan.

Aislamiento de errores por fuente. Cada proveedor envuelve su llamada HTTP en try/except. Un 429 de una fuente nunca hunde la búsqueda completa: obtienes resultados parciales más un mensaje claro sobre qué fuente falló.

Canonicalización de URL. merge_results() elimina los parámetros de seguimiento (utm_*, fbclid, gclid, ref) antes de la deduplicación, normaliza las mayúsculas en el host y descarta los fragmentos. Cuando Brave y Tavily devuelven el mismo artículo, lo ves una sola vez con also_found_in: [brave, tavily] y una puntuación reforzada.

Cliente HTTP compartido por llamada. httpx.AsyncClient con agrupación de conexiones (max_connections=20), tiempos de espera razonables (30s por defecto, 45s para fetch_url) y seguimiento automático de redirecciones. Un cliente nuevo por llamada porque los servidores MCP stdio procesan una solicitud a la vez y queremos un estado limpio.

Sin navegadores headless. Cero Playwright, Selenium, Puppeteer o rotación de proxies. Menor superficie de ataque, menos dependencias, sin huella de JVM/Chrome. Jina hace el trabajo pesado en los pocos sitios que necesitan renderizado de JS.

Comparación con alternativas

Pruebas

.venv/bin/python tests/e2e_protocol.py

Esto lanza el servidor real, realiza un handshake real de MCP initialize + tools/list y luego hace llamadas JSON-RPC en vivo contra cada herramienta y verifica que:

• Las APIs reales devuelven datos reales (no stubs)

• La respuesta de cada herramienta tiene la forma esperada

• Los estados de error se gestionan con elegancia

• search_web sin claves devuelve un mensaje claro de "establece las claves de API"

Última ejecución: 7/7 herramientas superan las pruebas contra APIs en vivo.

Solución de problemas

El servidor se inicia pero las herramientas no aparecen en mi cliente MCP

Comprueba hermes mcp list (o equivalente). El servidor está registrado con --command, lo que significa que Hermes ejecutará el lanzador directamente. Asegúrate de que el lanzador sea ejecutable:

chmod +x bin/web-research-mcp

fetch_url devuelve contenido truncado

Por diseño: el límite de 20k caracteres protege tu ventana de contexto. Para lecturas más largas, recupera la página tú mismo y pasa extractos a search_web para preguntas de seguimiento, o divide en secciones mediante varias llamadas.

search_web devuelve "No hay resultados web. Probablemente no hay ninguna clave de API configurada"

Necesitas al menos una de BRAVE_API_KEY o TAVILY_API_KEY configurada en web-research.env. Las otras 6 herramientas (Wikipedia, arXiv, HN, Stack Exchange, Crossref, fetch_url) funcionan todas sin claves.

Stack Exchange devuelve 400 Bad Request

Si has configurado un parámetro filter personalizado, la API rechaza los IDs de filtro desconocidos. Usa el filtro por defecto (omite el parámetro): devuelve más campos de los que necesitas, pero todo funciona. Este servidor usa el predeterminado.

El servidor falla en el primer lanzamiento

Comprueba stderr para ver el traceback real. Causa común: Python <3.10. Compruébalo con python3 --version.

Límites de tasa

Cada API sin clave tiene sus propios límites. Si los alcanzas:

• Wikipedia: ~200 req/min, identifícate con un User-Agent real (este servidor envía uno)

• arXiv: ~1 req/3s para usuarios no autenticados, por favor reduce la frecuencia

• Hacker News Algolia: 10k req/hora con clave de API, 5k sin ella

• Stack Exchange: 300 req/día sin clave (suficiente para sesiones de investigación)

• Crossref: añade mailto en el User-Agent (este servidor lo hace), y entonces el pool de cortesía es ilimitado

Desarrollo

Estructura del proyecto

web-research-mcp/
├── bin/
│   └── web-research-mcp          # Launcher: venv bootstrap + exec
├── src/web_research/
│   ├── __init__.py
│   ├── server.py                  # MCPServer + 7 @app.tool functions
│   └── providers.py               # 7 search backends + Result dataclass
├── tests/
│   └── e2e_protocol.py            # Real subprocess JSON-RPC test
├── web-research.env.example       # API key template
├── pyproject.toml                 # PEP 621, uv-installable
├── README.md
├── CHANGELOG.md
├── LICENSE
└── .gitignore

Añadir una nueva herramienta

1. Añade una función async a providers.py:

   async def search_my_source(query: str, max_results: int, client: httpx.AsyncClient) -> list[Result]:
       try:
           # ... your HTTP call ...
       except Exception as e:
           print(f"[my_source] error: {e}", flush=True)
           return []
       return [Result(title=..., url=..., snippet=..., source="my_source")]

2. Regístrala en server.py:

   @app.tool(name="search_my_source", description="...", annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
   async def search_my_source(query: Annotated[str, Field(description="Search query")], max_results: Annotated[int, Field(ge=1, le=10, default=5)] = 5) -> str:
       async with await _new_client() as client:
           res = await providers.search_my_source(query, max_results, client)
       return _format_results(query, res, "my_source") if res else f"No my_source results for: {query}"

3. Añade un caso de prueba en vivo en tests/e2e_protocol.py.

4. Actualiza la sección de Herramientas del README.

Estilo de código

• Python 3.10+, async-first

• Anotaciones de tipo en todas partes; deja que Pydantic derive el esquema JSON de MCP

• Cada proveedor envuelve su llamada de red en try/except y degrada a []

• Cliente HTTP por llamada (_new_client()) — no lo compartas entre llamadas en modo stdio

Contribuciones

Se aceptan PRs. Antes de abrir una:

1. Ejecuta la prueba e2e contra una instalación en vivo: .venv/bin/python tests/e2e_protocol.py

2. Añade un caso de prueba para cualquier herramienta nueva

3. Mantén providers.py independiente de los tipos específicos de MCP: debe ser reutilizable como módulo Python normal

4. No añadas dependencias de navegadores headless ni rotación de proxies: eso viola la tesis del proyecto

Para cambios importantes, abre primero un issue.

Licencia

MIT — consulta LICENSE.

Créditos

• Construido sobre el Model Context Protocol de Anthropic

• Usa Jina Reader para la recuperación limpia de páginas

• APIs de búsqueda: Brave, Tavily, Wikipedia, arXiv, Crossref, Hacker News Algolia, Stack Exchange