mcp-research

MCP-Server für Web-Recherchen, wissenschaftliche Arbeiten, Twitter/X, YouTube und Dateieinbindung. Acht Tools für KI-Assistenten – alles über das MCP-stdio-Protokoll. Enthält einen Anmeldedaten-Tresor für institutionellen Zugriff, CAPTCHA-Erkennung und token-effiziente Ausgabe.

Tools

Alle Tools sind schreibgeschützt – sie rufen Inhalte ab und transformieren sie, ohne jemals etwas zu verändern.

Related MCP server: Research Powerpack MCP

Installation

pip install mcp-research

Oder direkt mit uvx ausführen (keine Installation erforderlich):

uvx mcp-research

Optionale Extras:

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

Überprüfen Sie Ihr Setup:

mcp-research doctor

Verwendung mit Claude Code

Fügen Sie dies zur Claude Code MCP-Konfiguration hinzu (~/.claude/settings.json oder Projekt .mcp.json):

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

Verwendung mit Claude Desktop

Fügen Sie dies zu claude_desktop_config.json hinzu:

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

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen – es sind keine Konfigurationsdateien erforderlich (außer dem optionalen Tresor).

Tool-Details

web_search

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

Durchsucht das Web mit einer 3-stufigen Kaskade für maximale Zuverlässigkeit:

1. Brave Search API – schnell, hohe Qualität (erfordert BRAVE_API_KEY)

2. DuckDuckGo-Bibliothek – kein API-Schlüssel erforderlich, Wiederholungsversuche bei Ratenbegrenzung

3. DuckDuckGo HTML-Scraper – Fallback als letzte Instanz

Optionen:

• summarize: Ollama zur Zusammenfassung der Ergebnisse verwenden (erfordert laufendes Ollama)

• auto_fetch_top: Zusätzlich den vollständigen Inhalt des Top-Ergebnisses abrufen und zurückgeben

fetch_url

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

Ruft eine URL ab und konvertiert sie in sauberes Markdown:

• SSRF-Schutz: Blockiert Localhost, private IPs, Nicht-HTTP-Schemata

• Intelligente Wiederholung: Exponentielles Backoff bei 429/5xx, Validierung von Redirects pro Hop

• 24h-Cache: SHA-256-verschlüsselt, konfigurierbare TTL

• Inhaltsunterstützung: HTML → Markdown, JSON → Code-Block, Binär → abgelehnt

• Intelligente Kürzung: Bricht an Überschriften-/Absatzgrenzen ab, nicht mitten im Text

• CAPTCHA-Erkennung: Markiert Cloudflare-, hCaptcha-, reCAPTCHA-, Akamai-Sperren

• Token-effizient: Standardmäßig 15K Zeichen (~4K Token), einstellbar über max_chars

research

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

Verbund-Forschungspipeline:

1. Abfrage-Umschreibung – Ollama optimiert Ihre Frage in Suchbegriffe

2. Websuche – findet relevante Seiten (mit Erweiterung bei Null-Ergebnissen)

3. Paralleles Abrufen – ruft die Top-N-Seiten gleichzeitig ab

4. Zusammenfassen – Ollama fasst jede Seite zusammen

5. Synthetisieren – Ollama erstellt eine finale, zitierte Antwort

Tiefe-Stufen:

Alle Schritte funktionieren auch ohne Ollama – Sie erhalten weiterhin Suchergebnisse und Seiteninhalte.

youtube_essence

youtube_essence(url, mode="standard")

Extrahiert strukturierte Inhalte aus YouTube-Videos:

• Transkript: Automatische Untertitel oder Whisper-Transkription (lokal, privat)

• Zusammenfassung: KI-Zusammenfassung über Ollama

• Kernpunkte: Wichtige Erkenntnisse in Stichpunkten

• Kapitel: Zeitgestempelte Segmente

• Zitate: Bemerkenswerte Zitate (Deep-Modus)

Modi: quick (TL;DR), standard (+ Kapitel), deep (+ Zitate)

Erfordert yt-dlp. Optional: faster-whisper für reine Audio-Videos, ffmpeg für Medienextraktion.

deep_ingest

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

Extrahiert Text aus Dateien in einem Verzeichnis oder aus einer einzelnen Datei:

• Textdateien: .txt, .md, .json, .csv, Quellcode, etc.

• PDF: Über PyPDF2 (optionale Abhängigkeit)

• Office: .docx, .xlsx, .pptx (optionale Abhängigkeiten)

• Audio/Video: Whisper-Transkription (optional)

• Bilder: OCR über Ollama-Vision-Modell (optional)

Typ-Filter: text, pdf, audio, video, image, office

academic_lookup

academic_lookup(identifier, fetch_fulltext=True)

Löst wissenschaftliche Arbeiten anhand verschiedener Identifikatortypen auf:

• DOI: 10.xxxx/... → Crossref-Metadaten + Publisher-Redirect

• ArXiv: 2301.12345 → Abstract + PDF

• PubMed: PMID → E-Utilities-Metadaten → DOI-Kette

• URL: Erkennung der Publisher-Seite

Volltextzugriff über Anmeldedaten-Tresor:

• EZproxy-Umschreibung (Präfix- und Suffix-Modi)

• Bearer-Token, API-Schlüssel, Basic Auth, Cookie-Jar

• Automatische Publisher-Erkennung (IEEE, Springer, Elsevier, ACM, Wiley, Nature, JSTOR, etc.)

twitter_extract

twitter_extract(url, include_thread=False)

Extrahiert Tweets und Threads von X.com/Twitter unter Verwendung einer Strategiekaskade:

1. yt-dlp (primär) – funktioniert mit Cookie-Jar für authentifizierten Zugriff

2. Twitter API v2 – falls Bearer-Token im Tresor konfiguriert

3. HTML-Abruf – Cookie-basierter letzter Ausweg

Rückgabe: Text, Autor, Zeitstempel, Metriken (Likes, Retweets, Antworten), Medien-URLs.

vault_status

vault_status()

Zeigt geladene Anmeldeprofile, Übereinstimmungsmuster und Authentifizierungstypen – enthüllt niemals Geheimnisse. Überprüft auch die Verfügbarkeit optionaler Abhängigkeiten.

Anmeldedaten-Tresor

Erstellen Sie ~/.mcp-research/vault.yaml, um die Authentifizierung für geschützte Quellen zu konfigurieren:

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} wird aus Umgebungsvariablen aufgelöst – Geheimnisse werden niemals im Klartext gespeichert

• Das erste passende Profil gewinnt (Reihenfolge ist wichtig)

• Authentifizierungstypen: bearer, basic, api_key, cookie_jar, headers

• EZproxy-Modi: prefix (Basis-URL voranstellen) oder suffix (Domain-Umschreibung)

• Hot-Reload: Änderungen an der Tresor-Datei werden automatisch übernommen

Token-Effizienz

Alle Tools erzeugen standardmäßig eine kompakte Ausgabe, um keine Token des KI-Kontextfensters zu verschwenden:

Sicherheit & Robustheit

• SSRF-Schutz: Blockiert Localhost, private IPs, Link-Local, Nicht-HTTP-Schemata bei jedem Hop

• CAPTCHA-Erkennung: Identifiziert Cloudflare-, hCaptcha-, reCAPTCHA-, Akamai-, DDoS-Guard-Sperren

• Eingabevalidierung: Größenbeschränkungen, URL-Validierung, sicheres Folgen von Redirects

• Kein eval/exec: Keine dynamische Codeausführung

• Tresor-Sicherheit: Geheimnisse werden aus Umgebungsvariablen aufgelöst, repr() maskiert alle Authentifizierungswerte

• Cache-Isolierung: Verzeichnisberechtigungen nur für Besitzer (0o700)

• Graceful Degradation: Fehlende optionale Abhängigkeiten führen nicht zum Absturz – Funktionen werden mit klaren Meldungen eingeschränkt

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

Entwicklung

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

Changelog

v0.3.0

• Anmeldedaten-Tresor: YAML-Konfiguration unter ~/.mcp-research/vault.yaml mit Umgebungsvariablen-Interpolation, Glob-URL-Matching, EZproxy-Umschreibung, Hot-Reload

• Sitzungs-Pooling: Domain-spezifische Sitzungen mit Tresor-Auth-Injektion, Cookie-Jar-Unterstützung, Leerlauf-Entfernung

• CAPTCHA-Erkennung: Identifiziert Cloudflare, hCaptcha, reCAPTCHA, Akamai, DDoS-Guard, generische Bot-Sperren

• Wissenschaftliche Suche: DOI/ArXiv/PubMed-Auflösung, Crossref-Metadaten, institutioneller Volltextzugriff über Tresor

• Twitter/X-Extraktion: yt-dlp, API v2 und Cookie-basierter Zugriff mit Thread-Unterstützung

• Token-Effizienz: Standard-Ausgabebegrenzungen (~4K Token für Abruf, ~500 pro Forschungsquelle) zur Schonung des KI-Kontexts

• Doctor-Befehl: mcp-research doctor überprüft alle Abhängigkeiten und Konfigurationen

• Windows-Encoding-Fix: UTF-8 stdout/stderr-Wrapper verhindert cp1252-Abstürze

v0.2.0

• YouTube-Essenz: Transkriptextraktion, KI-Zusammenfassung, Kernpunkte, Kapitel, Zitate

• Deep Ingest: PDF, DOCX, XLSX, PPTX, Audio, Video, Bildtextextraktion

• Ollama-Integration: Abfrage-Umschreibung, Zusammenfassung, Synthese, Vision-OCR

• Suchprotokollierung: NDJSON-Ereignisprotokoll für alle Vorgänge

• Brave Search: Primäre Suchstufe mit API-Schlüssel-Unterstützung

v0.1.0

• Erstveröffentlichung: 3 Tools (web_search, fetch_url, research), SSRF-Schutz, Caching

Lizenz

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