web-search-mcp

Un servidor de investigación (MCP) completo y listo para producción. Proporciona a tus clientes LLM acceso en tiempo real a la web, datos y más.

GitHub

Prueba este MCPPatrocinado

Documentación

Web Search MCP

Un servidor integral del Protocolo de Contexto de Modelo (MCP) construido con FastMCP que proporciona a los LLM acceso en tiempo real y de alta fidelidad a la web. Este servidor agrega múltiples motores de búsqueda, plataformas sociales y herramientas de desarrollo en una única interfaz, permitiendo a los agentes de IA realizar investigaciones profundas, rastrear el sentimiento de la comunidad y analizar documentación técnica.

Documentos de diseño → wiki — guía de selección de herramientas, matriz de decisiones, flujos de trabajo recomendados, estado de herramientas y peculiaridades conocidas, configuración de plugins y estándares de desarrollo.

🚀 Características

El servidor proporciona un conjunto diverso de herramientas categorizadas por su caso de uso principal:

🌐 Búsqueda Web General y Recuperación

Herramienta	Descripción	Mejor Para
`search_web`	Búsqueda web rápida mediante DuckDuckGo o Exa (SDK). Admite delimitación por dominio, filtrado por fecha, modo de noticias y región geográfica. El proveedor automático predeterminado intenta DDG primero y recurre a Exa.	Consultas rápidas, búsquedas de alto volumen, paginación, cobertura amplia
`fetch_page`	Extracción de texto de alta fidelidad desde URLs con evasión de detección de bots, protección SSRF (bloquea IPs privadas/internas) y múltiples formatos de salida.	Lectura profunda de resultados de búsqueda, obtención de URLs independientes

💬 Inteligencia Social y Comunitaria

Herramienta	Descripción	Mejor Para
`search_reddit`	Búsqueda sin clave para discusiones comunitarias, opiniones y experiencias de usuarios reales mediante RSS + enriquecimiento Shreddit.	Reseñas de productos, sentimiento comunitario, solución de problemas
`search_hackernews`	Discursos técnicos, noticias de startups y opiniones de desarrolladores mediante la API Algolia HN.	Noticias tecnológicas, discusiones de startups, opiniones de desarrolladores
`search_github`	Búsqueda de Issues y PRs para rastrear errores, solicitudes de funciones y sentimiento comunitario. Requiere CLI `gh` o `GITHUB_TOKEN`.	Rastreo de errores, solicitudes de funciones, sentimiento comunitario
`get_github_issue`	Obtención de hilos de conversación completos de Issues/PRs de GitHub, ordenados por reacciones con metadatos de autor/fecha/reacciones.	Análisis profundo de issues/PRs específicos
`search_x`	Discurso en tiempo real y noticias de última hora mediante la API Xquik o el CLI Bird incluido (requiere cookies de sesión o clave API).	Noticias de última hora, reacciones comunitarias, señales de participación
`search_linkedin`	Búsqueda de personas, empresas, empleos y publicaciones mediante DuckDuckGo + Jina Reader (r.jina.ai). No se necesita clave API.	Perfiles profesionales, investigación de empresas, búsqueda de empleo

🎓 Académico y Referencia

Herramienta	Descripción	Mejor Para
`search_arxiv`	Búsqueda especializada para artículos académicos con prefijos de campo Lucene (`au:`, `ti:`, `cat:`, `abs:`).	Artículos de investigación, citas, revisiones de literatura
`search_wikipedia`	Resúmenes factuales e investigación de antecedentes mediante la API MediaWiki.	Resúmenes factuales, investigación de antecedentes, citas

📋 Requisitos Previos

Requisito	Versión	Notas
Python	3.11+	Requerido
uv	Última	Recomendado para instalación y gestión del entorno

Herramientas Externas Opcionales

Herramienta	Requerida Para	Instalación
CLI `gh`	Búsqueda autenticada de GitHub y recuperación de issues (límites de tasa más altos)	`brew install gh` / github.com/cli/cli
Node.js	CLI Bird incluido para búsqueda en X/Twitter (no necesario con `XQUIK_API_KEY`)	22+ recomendado; `brew install node@22` / nodejs.org

⚙️ Instalación

Tienes tres opciones según tu caso de uso:

Opción A: Ejecución Rápida (mediante `uvx`)

La forma más rápida de probarlo sin clonar el repositorio. Añádelo a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "Web-Research": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sydasif/web-search-mcp.git",
        "web-search-mcp"
      ]
    }
  }
}

Opción B: Instalación Permanente

Los tiempos de inicio más rápidos con una herramienta instalada globalmente:

uv tool install git+https://github.com/sydasif/web-search-mcp.git

Luego configura tu cliente MCP:

{
  "mcpServers": {
    "Web-Research": {
      "command": "web-search-mcp"
    }
  }
}

Opción C: Instalación para Desarrollo

Si deseas modificar el código o contribuir:

git clone https://github.com/sydasif/web-search-mcp.git
cd web-search-mcp
uv sync
uv run web-search-mcp

Verificar que Funciona

Una vez que el servidor esté en ejecución, prueba una búsqueda simple:

search_web(query="current weather in Tokyo")

🔐 Configuración y Autenticación

La mayoría de las herramientas funcionan listas para usar sin configuración. Las siguientes variables de entorno solo son necesarias para funciones premium o autenticadas.

Referencia de Variables de Entorno

Variable	Requerida Para	Cómo Obtenerla
`EXA_API_KEY`	Búsqueda semántica Exa AI (respaldo opcional)	Regístrate en exa.ai
`GITHUB_TOKEN`	Límites de tasa más altos de la API de GitHub (opcional)	Genera un PAT de GitHub
`AUTH_TOKEN`	Búsqueda en X/Twitter mediante CLI Bird (requerido)	Cookie de sesión de x.com (ver más abajo)
`CT0`	Búsqueda en X/Twitter mediante CLI Bird (requerido)	Cookie de sesión de x.com (ver más abajo)
`XQUIK_API_KEY`	Búsqueda en X/Twitter mediante API Xquik (alternativa a cookies)	Regístrate en xquik.ai

Configuración de Autenticación de GitHub

Opción 1 — Recomendada: Usar CLI gh

gh auth login

El servidor detecta tu sesión local automáticamente.

Opción 2: Token Manual

export GITHUB_TOKEN="ghp_your_token_here"

Configuración de Autenticación de X/Twitter

La búsqueda en X/Twitter requiere ya sea cookies de sesión o una clave API.

Opción 1 — Cookies de Sesión (CLI Bird):

Inicia sesión en x.com en tu navegador.
Abre DevTools (F12) → Application (o Storage) → Cookies → x.com.
Copia los valores de auth_token y ct0.
Expórtalos en el shell donde se ejecuta el servidor MCP:
```
export AUTH_TOKEN="your_auth_token"
export CT0="your_ct0"
```
Nota: Estas son cookies de sesión. Si las búsquedas devuelven 401, actualízalas cerrando sesión y volviendo a iniciarla.

Opción 2 — Clave API Xquik (Recomendada):

Regístrate en xquik.ai para obtener una clave API.
Expórtala:
```
export XQUIK_API_KEY="your_xquik_key"
```
Esto elimina por completo la dependencia del CLI Bird de Node.js.

Configuración de Exa AI (Opcional)

Exa proporciona búsqueda semántica y respaldo para páginas con mucho JavaScript:

export EXA_API_KEY="your_exa_key"

💡 Ejemplos de Uso

Investigación Web

# Broad search (auto: DDG first, falls back to Exa on error or zero results)
search_web(query="Latest NVIDIA H200 benchmarks")

# Force DDG explicitly
search_web(query="uv package manager", provider="ddg")

# Force Exa explicitly
search_web(query="uv package manager", provider="exa")

# Targeted documentation search
search_web(query="useEffect cleanup", domain="react.dev")

# News with region filter
search_web(query="elections", search_type="news", region="us-en", provider="exa")

# Date-filtered search
search_web(query="uv package manager", time_range="w", provider="auto")

# Deep read a page
fetch_page(url="https://docs.python.org/3/library/os.html")

Análisis Técnico

# Track GitHub issues/PRs
search_github(query="uv package manager")

# Get full GitHub issue thread
get_github_issue(url="https://github.com/astral-sh/uv/issues/1")

Sentimiento Comunitario

# Reddit discussions
search_reddit(query="Best mechanical keyboards 2024", subreddits=["MechanicalKeyboards"])

# Hacker News technical discourse
search_hackernews(query="MCP server architecture")

# LinkedIn professional search
search_linkedin(query="site reliability engineer", content_type="people")
search_linkedin(query="machine learning startup", content_type="companies")
search_linkedin(query="kubernetes devops", content_type="jobs")
search_linkedin(query="AI agents", content_type="posts")

Investigación Académica

# arXiv paper search with field prefixes
search_arxiv(query="au:Goodfellow AND cat:cs.LG")
search_arxiv(query="transformer attention", sort_by="submitted_date")

# Wikipedia background research
search_wikipedia(query="Quantum computing")

🏗️ Estructura del Proyecto

web_search_mcp/
├── server.py              # Entry point: FastMCP init, @mcp.tool registrations
├── search/                # Search engine implementations
│   ├── ddg.py             # DuckDuckGo search + trafilatura page fetch
│   └── exa.py             # Exa SDK search & content fetch (lazy-init client)
├── social/                # Community platform integrations
│   ├── github.py          # GitHub Search API + gh CLI issue rendering
│   ├── hackernews.py      # Algolia HN API + comment enrichment
│   ├── linkedin/          # LinkedIn search via DDG + Jina Reader
│   │   ├── __init__.py    # LinkedIn search tool registration
│   │   └── client.py      # DDG search + Jina Reader enrichment
│   ├── reddit/            # RSS + Shreddit keyless pipeline
│   │   ├── client.py      # HTTP client with RSS parsing
│   │   ├── parsers.py     # RSS/HTML parsers
│   │   └── shreddit.py    # Shreddit comment enrichment
│   └── x.py               # X/Twitter search via Xquik API or vendored Bird CLI
├── tools/                 # Specialized reference utilities
│   ├── arxiv.py           # arXiv paper search (Lucene field prefixes)
│   └── wikipedia.py       # Wikipedia MediaWiki API
├── _config/               # Settings, env vars, rate limits, depth tiers
│   ├── settings.py        # pydantic-settings (EXA_API_KEY, SEARCH_MCP_ prefix)
│   └── limits.py          # Per-platform quick/default/deep limits, timeouts
├── _http/                 # Shared HTTP + SSRF protection
│   └── client.py          # validate_url, http_client, get_json_client
├── _models/               # Pydantic request/response models
│   ├── requests.py        # SearchRequest
│   ├── responses.py       # ErrorResponse, SearchResponse, PageResponse
│   └── types.py           # Depth, ResponseFormat, SearchType, FetchOutputFormat
├── _utils/                # Shared helpers
│   ├── formatting.py      # Markdown formatters, date/epoch utils
│   ├── rate_limiter.py    # Token-bucket rate limiter
│   └── scoring.py         # Relevance scoring
└── vendor/                # Vendored third-party tools
    └── bird-search/       # Node.js CLI for X/Twitter search (fallback when XQUIK_API_KEY unset)

🛠️ Flujo de Implementación de Herramientas

Al añadir una nueva herramienta:

Implementa la lógica en el módulo apropiado (search/, social/ o tools/)
Define los modelos en _models/ (tipos de solicitud/respuesta)
Regístrala en server.py usando el decorador @mcp.tool con un docstring claro (sirve como descripción de la herramienta para el LLM)

📐 Decisiones de Diseño

search-backend-split — Por qué search_web unifica DuckDuckGo y Exa detrás de un único parámetro provider en lugar de exponer dos herramientas separadas.

🧪 Pruebas

# Run all tests
uv run pytest

# Run a single test file
uv run pytest tests/test_module.py

# Run a specific test
uv run pytest tests/test_module.py::test_function_name

# Run with coverage
uv run pytest --cov=web_search_mcp

🔧 Solución de Problemas

Problema	Causa Probable	Solución
Errores de autenticación en una herramienta	Variable de entorno no configurada en el shell del servidor	Exporta la variable en el mismo shell donde se ejecuta el proceso del servidor MCP
GitHub devuelve resultados vacíos	No autenticado	Ejecuta `gh auth login` o configura `GITHUB_TOKEN`
`search_x` devuelve 401	Cookies de sesión X caducadas	Vuelve a extraer `auth_token` y `ct0` de x.com
`fetch_page` bloqueado por Cloudflare	Detección de bots	Prueba el parámetro `backend="curl"`
`search_arxiv` devuelve 503	Mantenimiento de arXiv aguas arriba	Espera unos minutos y reintenta
La herramienta dice "Query cannot be empty"	Consulta faltante o vacía	Proporciona una consulta de búsqueda no vacía

🤝 Contribuciones

Haz un fork del repositorio.
Crea una rama de funcionalidad: git checkout -b feat/my-new-tool
Asegúrate de que todas las pruebas pasen: uv run pytest
Envía una solicitud de pull con una descripción detallada de los cambios.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT.