mcp-research

Servidor MCP para investigación web, artículos académicos, Twitter/X, YouTube e ingesta de archivos. Ocho herramientas para asistentes de IA, todo a través del protocolo stdio de MCP. Incluye un almacén de credenciales para acceso institucional, detección de CAPTCHA y salida eficiente en tokens.

Herramientas

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

Related MCP server: Research Powerpack MCP

Instalación

pip install mcp-research

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

uvx mcp-research

Extras opcionales:

pip install 'mcp-research[twitter]' # yt-dlp for Twitter extraction
pip install 'mcp-research[youtube]' # yt-dlp + faster-whisper for YouTube
pip install 'mcp-research[academic]' # PyPDF2 for academic PDFs
pip install 'mcp-research[ingest]' # PDF, DOCX, XLSX, PPTX, audio support
pip install 'mcp-research[all]' # everything

Comprueba tu configuración:

mcp-research doctor

Uso con Claude Code

Añádelo a tu configuración de 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..."
 }
 }
 }
}

Configuración

Toda la configuración se realiza mediante variables de entorno; no se necesitan archivos de configuración (excepto el almacén opcional).

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ápido, alta calidad (requiere BRAVE_API_KEY)

2. Biblioteca DuckDuckGo — no requiere clave de API, reintenta ante límites 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=15000)

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: 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

• Detección de CAPTCHA: Marca muros de Cloudflare, hCaptcha, reCAPTCHA, Akamai

• Eficiente en tokens: 15K caracteres predeterminados (~4K tokens), ajustable mediante max_chars

research

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

Canal 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 páginas principales simultáneamente

4. Resumir — Ollama resume cada página

5. Sintetizar — Ollama produce una respuesta final citada

Niveles de profundidad:

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

youtube_essence

youtube_essence(url, mode="standard")

Extrae contenido estructurado de vídeos de YouTube:

• Transcripción: Subtítulos automáticos o transcripción Whisper (local, privada)

• Resumen: Resumen de IA mediante Ollama

• Puntos clave: Conclusiones en viñetas

• Capítulos: Segmentos con marca de tiempo

• Citas: Citas notables (modo profundo)

Modos: quick (TL;DR), standard (+ capítulos), deep (+ citas)

Requiere yt-dlp. Opcional: faster-whisper para vídeos solo de audio, ffmpeg para extracción de medios.

deep_ingest

deep_ingest(path, include_types="", max_files=200, summarize=False)

Extrae texto de archivos en un directorio o un solo archivo:

• Archivos de texto: .txt, .md, .json, .csv, código fuente, etc.

• PDF: Vía PyPDF2 (dependencia opcional)

• Office: .docx, .xlsx, .pptx (dependencias opcionales)

• Audio/Vídeo: Transcripción Whisper (opcional)

• Imágenes: OCR mediante modelo de visión de Ollama (opcional)

Filtro de tipo: text, pdf, audio, video, image, office

academic_lookup

academic_lookup(identifier, fetch_fulltext=True)

Resuelve artículos académicos de múltiples tipos de identificadores:

• DOI: 10.xxxx/... → metadatos de Crossref + redirección del editor

• ArXiv: 2301.12345 → resumen + PDF

• PubMed: PMID → metadatos de E-utilities → cadena DOI

• URL: Detección de página del editor

Acceso a texto completo mediante almacén de credenciales:

• Reescritura EZproxy (modos prefijo y sufijo)

• Token de portador (bearer), clave de API, autenticación básica, tarro de cookies

• Detección automática de editor (IEEE, Springer, Elsevier, ACM, Wiley, Nature, JSTOR, etc.)

twitter_extract

twitter_extract(url, include_thread=False)

Extrae tweets e hilos de X.com/Twitter usando una cascada de estrategias:

1. yt-dlp (principal) — funciona con tarro de cookies para acceso autenticado

2. Twitter API v2 — si el token de portador está configurado en el almacén

3. Obtención HTML — último recurso basado en cookies

Devuelve: texto, autor, marca de tiempo, métricas (me gusta, retweets, respuestas), URLs de medios.

vault_status

vault_status()

Muestra perfiles de credenciales cargados, patrones de coincidencia y tipos de autenticación — nunca expone secretos. También comprueba la disponibilidad de dependencias opcionales.

Almacén de credenciales

Crea ~/.mcp-research/vault.yaml para configurar la autenticación para fuentes protegidas:

version: 1
profiles:
 # University EZproxy for IEEE
 ieee-university:
 match: "*.ieee.org/**"
 ezproxy:
 base_url: "https://ezproxy.myuniversity.edu/login?url="
 mode: prefix

 # Springer via API key
 springer:
 match: "*.springer.com/**"
 auth:
 type: api_key
 header: "X-ApiKey"
 value: "${SPRINGER_API_KEY}"

 # X.com via browser cookies
 twitter:
 match: "*.x.com/**"
 auth:
 type: cookie_jar
 path: "${HOME}/.mcp-research/cookies/twitter.txt"

• ${VAR} resuelto a partir de variables de entorno — los secretos nunca se almacenan en texto plano

• Gana el primer perfil coincidente (el orden importa)

• Tipos de autenticación: bearer, basic, api_key, cookie_jar, headers

• Modos EZproxy: prefix (anteponer URL base) o suffix (reescritura de dominio)

• Recarga en caliente: los cambios en el archivo del almacén se detectan automáticamente

Eficiencia de tokens

Todas las herramientas producen una salida compacta de forma predeterminada para evitar desperdiciar tokens de la ventana de contexto de la IA:

Seguridad y robustez

• Protección SSRF: Bloquea localhost, IPs privadas, link-local, esquemas no HTTP en cada salto

• Detección de CAPTCHA: Identifica muros de Cloudflare, hCaptcha, reCAPTCHA, Akamai, DDoS-Guard

• Validación de entrada: Límites de tamaño, validación de URL, seguimiento seguro de redirecciones

• Sin eval/exec: Sin ejecución de código dinámico

• Seguridad del almacén: Secretos resueltos desde variables de entorno, repr() redacta todos los valores de autenticación

• Aislamiento de caché: Permisos de directorio solo para el propietario (0o700)

• Degradación elegante: Las dependencias opcionales faltantes no bloquean el sistema — las funciones se degradan con mensajes claros

CLI

mcp-research serve # Run MCP stdio server (default)
mcp-research search "query" # Search the web
mcp-research fetch https://example.com # Fetch URL to markdown
mcp-research youtube https://youtu.be/... # Extract YouTube video
mcp-research ingest ./docs/ # Extract text from files
mcp-research academic "10.1109/..." # Resolve academic paper
mcp-research tweet https://x.com/.../123 # Extract tweet
mcp-research vault # Show vault profiles
mcp-research doctor # Check dependencies

Desarrollo

git clone https://github.com/MABAAM/Maibaamcrawler.git
cd Maibaamcrawler
pip install -e ".[all]"
pytest tests/ -v
python -m mcp_research

Registro de cambios

v0.3.0

• Almacén de credenciales: Configuración YAML en ~/.mcp-research/vault.yaml con interpolación de variables de entorno, coincidencia de URL con glob, reescritura EZproxy, recarga en caliente

• Agrupación de sesiones: Sesiones por dominio con inyección de autenticación del almacén, soporte para tarro de cookies, desalojo por inactividad

• Detección de CAPTCHA: Identifica muros de Cloudflare, hCaptcha, reCAPTCHA, Akamai, DDoS-Guard, muros de bots genéricos

• Búsqueda académica: Resolución DOI/ArXiv/PubMed, metadatos Crossref, acceso institucional a texto completo mediante almacén

• Extracción de Twitter/X: yt-dlp, API v2 y acceso basado en cookies con soporte para hilos

• Eficiencia de tokens: Límites de salida predeterminados (~4K tokens para fetch, ~500 por fuente de investigación) para preservar el contexto de la IA

• Comando doctor: mcp-research doctor comprueba todas las dependencias y la configuración

• Corrección de codificación en Windows: El envoltorio UTF-8 stdout/stderr evita bloqueos cp1252

v0.2.0

• Esencia de YouTube: Extracción de transcripción, resumen de IA, puntos clave, capítulos, citas

• Ingesta profunda: Extracción de texto de PDF, DOCX, XLSX, PPTX, audio, vídeo, imagen

• Integración con Ollama: Reescritura de consultas, resumen, síntesis, OCR de visión

• Registro de búsqueda: Registro de eventos NDJSON para todas las operaciones

• Brave Search: Nivel de búsqueda principal con soporte para clave de API

v0.1.0

• Lanzamiento inicial: 3 herramientas (web_search, fetch_url, research), protección SSRF, almacenamiento en caché

Licencia

MIT

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• academic_lookupA
• deep_ingestA
• fetch_urlA
• researchA
• twitter_extractA
• vault_statusA
• web_searchA
• youtube_essenceA