mcp-research

Un servidor MCP (Model Context Protocol) independiente que proporciona herramientas de investigación web. Tres herramientas probadas para asistentes de IA: buscar en la web, obtener y convertir páginas a markdown, y ejecutar investigaciones compuestas de múltiples fuentes, todo a través del protocolo stdio de MCP.

Herramientas

Todas las herramientas son de solo lectura: obtienen y transforman contenido web público, nunca modifican nada.

Instalación

pip install mcp-research

O ejecútalo directamente con uvx (sin instalación):

uvx mcp-research

Configuración

Toda la configuración se realiza mediante variables de entorno; no se necesitan archivos de configuración.

Uso con Claude Code

Añádelo a tu configuración MCP de Claude Code (~/.claude/settings.json o .mcp.json del proyecto):

{
  "mcpServers": {
    "research": {
      "command": "uvx",
      "args": ["mcp-research"],
      "env": {
        "BRAVE_API_KEY": "BSA...",
        "OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}

Uso con Claude Desktop

Añádelo a claude_desktop_config.json:

{
  "mcpServers": {
    "research": {
      "command": "uvx",
      "args": ["mcp-research"],
      "env": {
        "BRAVE_API_KEY": "BSA..."
      }
    }
  }
}

Detalles de las herramientas

web_search

web_search(query, max_results=5, summarize=False, auto_fetch_top=False)

Busca en la web utilizando una cascada de 3 niveles para una máxima fiabilidad:

1. Brave Search API — rápida, de alta calidad (requiere BRAVE_API_KEY)

2. Librería DuckDuckGo — no requiere clave de API, reintenta en caso de límite de tasa

3. HTML scraper de DuckDuckGo — alternativa de último recurso

Opciones:

• summarize: Usar Ollama para resumir resultados (requiere tener Ollama en ejecución)

• auto_fetch_top: También obtener y devolver el contenido completo del resultado principal

fetch_url

fetch_url(url, summarize=False, max_chars=50000)

Obtiene una URL y la convierte a markdown limpio:

• Protección SSRF: Bloquea localhost, IPs privadas, esquemas no HTTP

• Reintento inteligente: Retroceso exponencial en 429/5xx, validación de redirección por salto

• Caché de 24h: Con clave SHA-256, TTL configurable

• Soporte de contenido: HTML → markdown, JSON → bloque de código, binario → rechazado

• Truncamiento inteligente: Corta en límites de encabezado/párrafo, no a mitad del texto

research

research(query, depth="standard", context="")

Proceso de investigación compuesto:

1. Reescritura de consulta — Ollama optimiza tu pregunta en palabras clave de búsqueda

2. Búsqueda web — encuentra páginas relevantes (con expansión de reintento si hay cero resultados)

3. Obtención paralela — obtiene las N mejores páginas simultáneamente

4. Resumen — Ollama resume cada página

5. Síntesis — Ollama produce una respuesta final con citas

Niveles de profundidad:

Todos los pasos se degradan correctamente sin Ollama: sigues obteniendo resultados de búsqueda y contenido de página sin procesar.

Desarrollo

git clone https://github.com/MABAAM/Maibaamcrawler.git
cd Maibaamcrawler
pip install -e .
python -m mcp_research

Licencia

MIT