mcp-research

MCP-сервер для веб-исследований, поиска научных статей, работы с Twitter/X, YouTube и обработки файлов. Восемь инструментов для ИИ-ассистентов — все через протокол MCP stdio. Включает хранилище учетных данных для институционального доступа, обнаружение CAPTCHA и вывод, оптимизированный по количеству токенов.

Инструменты

Все инструменты работают только для чтения — они получают и преобразуют контент, ничего не изменяя.

Related MCP server: Research Powerpack MCP

Установка

pip install mcp-research

Или запустите напрямую с помощью uvx (без установки):

uvx mcp-research

Дополнительные опции:

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

Проверьте свою настройку:

mcp-research doctor

Использование с Claude Code

Добавьте в конфигурацию MCP Claude Code (~/.claude/settings.json или проектный файл .mcp.json):

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

Использование с Claude Desktop

Добавьте в claude_desktop_config.json:

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

Конфигурация

Вся конфигурация осуществляется через переменные окружения — файлы конфигурации не требуются (за исключением опционального хранилища).

Подробности об инструментах

web_search

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

Поиск в сети с использованием 3-уровневого каскада для максимальной надежности:

1. Brave Search API — быстрый, качественный (требует BRAVE_API_KEY)

2. Библиотека DuckDuckGo — ключ API не нужен, повторные попытки при ограничении скорости

3. HTML-скрейпер DuckDuckGo — крайний вариант

Опции:

• summarize: Использовать Ollama для обобщения результатов (требуется запущенный Ollama)

• auto_fetch_top: Также загрузить и вернуть полный контент первого результата

fetch_url

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

Загружает URL и преобразует его в чистый markdown:

• Защита от SSRF: Блокирует localhost, частные IP, не-HTTP схемы

• Умный повтор: Экспоненциальная задержка при 429/5xx, проверка редиректов на каждом этапе

• 24-часовой кэш: Ключ SHA-256, настраиваемое время жизни (TTL)

• Поддержка контента: HTML → markdown, JSON → блок кода, бинарные файлы → отклоняются

• Умное усечение: Разрыв по границам заголовков/абзацев, а не посреди текста

• Обнаружение CAPTCHA: Помечает стены Cloudflare, hCaptcha, reCAPTCHA, Akamai

• Эффективность токенов: По умолчанию 15 тыс. символов (~4 тыс. токенов), настраивается через max_chars

research

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

Составной конвейер исследований:

1. Переписывание запроса — Ollama оптимизирует ваш вопрос в поисковые ключевые слова

2. Веб-поиск — находит релевантные страницы (с расширением поиска при нулевых результатах)

3. Параллельная загрузка — параллельно загружает топ N страниц

4. Обобщение — Ollama обобщает каждую страницу

5. Синтез — Ollama создает итоговый ответ со ссылками

Уровни глубины:

Все шаги корректно работают без Ollama — вы все равно получите результаты поиска и контент страниц.

youtube_essence

youtube_essence(url, mode="standard")

Извлекает структурированный контент из видео YouTube:

• Транскрипт: Автоматические субтитры или транскрипция Whisper (локально, приватно)

• Резюме: ИИ-резюме через Ollama

• Ключевые моменты: Основные выводы списком

• Главы: Сегменты с временными метками

• Цитаты: Примечательные цитаты (глубокий режим)

Режимы: quick (TL;DR), standard (+ главы), deep (+ цитаты)

Требуется yt-dlp. Опционально: faster-whisper для аудио-видео, ffmpeg для извлечения медиа.

deep_ingest

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

Извлекает текст из файлов в директории или одного файла:

• Текстовые файлы: .txt, .md, .json, .csv, исходный код и т.д.

• PDF: Через PyPDF2 (опциональная зависимость)

• Office: .docx, .xlsx, .pptx (опциональные зависимости)

• Аудио/Видео: Транскрипция Whisper (опционально)

• Изображения: OCR через vision-модель Ollama (опционально)

Фильтр типов: text, pdf, audio, video, image, office

academic_lookup

academic_lookup(identifier, fetch_fulltext=True)

Разрешает научные статьи по нескольким типам идентификаторов:

• DOI: 10.xxxx/... → метаданные Crossref + редирект издателя

• ArXiv: 2301.12345 → аннотация + PDF

• PubMed: PMID → метаданные E-utilities → цепочка DOI

• URL: Обнаружение страницы издателя

Доступ к полному тексту через хранилище учетных данных:

• Переписывание EZproxy (режимы префикса и суффикса)

• Bearer-токен, API-ключ, базовая аутентификация, cookie jar

• Автоматическое обнаружение издателя (IEEE, Springer, Elsevier, ACM, Wiley, Nature, JSTOR и др.)

twitter_extract

twitter_extract(url, include_thread=False)

Извлекает твиты и ветки из X.com/Twitter, используя каскад стратегий:

1. yt-dlp (основная) — работает с cookie jar для аутентифицированного доступа

2. Twitter API v2 — если в хранилище настроен bearer-токен

3. HTML-загрузка — крайний вариант на основе cookie

Возвращает: текст, автора, временную метку, метрики (лайки, ретвиты, ответы), URL медиа.

vault_status

vault_status()

Показывает загруженные профили учетных данных, шаблоны соответствия и типы аутентификации — никогда не раскрывает секреты. Также проверяет доступность опциональных зависимостей.

Хранилище учетных данных

Создайте ~/.mcp-research/vault.yaml для настройки аутентификации для защищенных источников:

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} разрешается из переменных окружения — секреты никогда не хранятся в открытом виде

• Побеждает первый подходящий профиль (порядок важен)

• Типы аутентификации: bearer, basic, api_key, cookie_jar, headers

• Режимы EZproxy: prefix (добавление к базовому URL) или suffix (переписывание домена)

• Горячая перезагрузка: изменения в файле хранилища подхватываются автоматически

Эффективность токенов

Все инструменты по умолчанию создают компактный вывод, чтобы не тратить токены контекстного окна ИИ:

Безопасность и надежность

• Защита от SSRF: Блокирует localhost, частные IP, link-local, не-HTTP схемы на каждом этапе

• Обнаружение CAPTCHA: Идентифицирует стены Cloudflare, hCaptcha, reCAPTCHA, Akamai, DDoS-Guard

• Валидация ввода: Ограничения размера, проверка URL, безопасное следование редиректам

• Без eval/exec: Нет выполнения динамического кода

• Безопасность хранилища: Секреты разрешаются из переменных окружения, repr() скрывает все значения аутентификации

• Изоляция кэша: Права доступа только для владельца (0o700)

• Корректная деградация: Отсутствие опциональных зависимостей не приводит к сбою — функции деградируют с понятными сообщениями

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

Разработка

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

Журнал изменений

v0.3.0

• Хранилище учетных данных: YAML-конфиг в ~/.mcp-research/vault.yaml с интерполяцией переменных окружения, сопоставлением URL по glob, переписыванием EZproxy, горячей перезагрузкой

• Пул сессий: Сессии для каждого домена с внедрением аутентификации из хранилища, поддержкой cookie jar, вытеснением при простое

• Обнаружение CAPTCHA: Идентифицирует Cloudflare, hCaptcha, reCAPTCHA, Akamai, DDoS-Guard, общие бот-стены

• Научный поиск: Разрешение DOI/ArXiv/PubMed, метаданные Crossref, институциональный доступ к полному тексту через хранилище

• Извлечение Twitter/X: yt-dlp, API v2 и доступ на основе cookie с поддержкой веток

• Эффективность токенов: Ограничения вывода по умолчанию (~4 тыс. токенов для загрузки, ~500 на источник исследования) для сохранения контекста ИИ

• Команда doctor: mcp-research doctor проверяет все зависимости и конфигурацию

• Исправление кодировки Windows: Обертка UTF-8 stdout/stderr предотвращает сбои cp1252

v0.2.0

• YouTube essence: Извлечение транскрипта, ИИ-резюме, ключевые моменты, главы, цитаты

• Deep ingest: Извлечение текста из PDF, DOCX, XLSX, PPTX, аудио, видео, изображений

• Интеграция Ollama: Переписывание запросов, обобщение, синтез, vision OCR

• Логирование поиска: Журнал событий NDJSON для всех операций

• Brave Search: Основной уровень поиска с поддержкой API-ключа

v0.1.0

• Первый выпуск: 3 инструмента (web_search, fetch_url, research), защита от SSRF, кэширование

Лицензия

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