Paper Search MCP

Сервер Model Context Protocol (MCP) для поиска и загрузки академических статей из нескольких источников. Проект придерживается стратегии «сначала бесплатно»: приоритет отдаётся открытым и публичным источникам данных, поддерживаются необязательные API-ключи, когда они улучшают стабильность или охват, а коннекторы для конкретных источников остаются расширяемыми для продвинутых пользователей.

Содержание

• Обзор

• Принципы проекта

• Возможности

• Стратегия источников

• Уведомление о Sci-Hub

• Установка

  • Claude Code (Skill)

  • Метод 1 — Smithery

  • Метод 2 — uvx

  • Метод 3 — uv

  • Метод 4 — pip

  • Метод 5 — npx

  • Метод 6 — Docker

  • Метод 7 — Клонирование и запуск из исходников

  • Переменные окружения

• Вклад

• Демо

• История звёзд

• Лицензия

• TODO

Related MCP server: Academic Paper MCP HTTP/SSE Server

Обзор

paper-search-mcp — это инструмент на Python для поиска и загрузки академических статей с различных платформ. Он предоставляет инструменты для поиска статей, загрузки PDF-файлов и извлечения текста, что делает его идеальным для исследователей и рабочих процессов на основе ИИ. Его можно использовать как MCP-сервер (для Claude Desktop и других MCP-клиентов) или как навык Claude Code с CLI-интерфейсом.

Принципы проекта

• Сначала бесплатно: Публичные и открытые источники — это основная дорожная карта. Платные или ограниченные источники не являются основным направлением этого проекта.

• Необязательные API-ключи: API-ключи поддерживаются только тогда, когда они улучшают стабильность, лимиты запросов или качество метаданных. MCP должен оставаться работоспособным без них, когда это возможно.

• Дружелюбное к LLM извлечение: Результаты поиска должны быть стандартизированы, дедуплицированы и максимально полными для последующих рабочих процессов LLM.

• Прозрачность источников: Разные источники имеют разные сильные стороны. MCP должен явно показывать эти компромиссы, а не делать вид, что каждый источник поддерживает полнотекстовое извлечение.

Возможности

• Двухуровневая архитектура:

  • Уровень 1 (единые инструменты): Высокоуровневые search_papers для многопоточного поиска и дедупликации, и download_with_fallback, использующий открытые ссылки издателей с последовательными запасными вариантами.

  • Уровень 2 (коннекторы платформ): Модульные коннекторы для конкретных академических платформ (arXiv, PubMed, bioRxiv, Semantic Scholar и т.д.) с интеллектуальным извлечением DOI через регулярные выражения или поля API.

• Поддержка нескольких источников: Поиск и загрузка статей из arXiv, PubMed, bioRxiv, medRxiv, Google Scholar, IACR ePrint Archive, Semantic Scholar, Crossref, OpenAlex, PubMed Central (PMC), CORE, Europe PMC, dblp, OpenAIRE, CiteSeerX, DOAJ, BASE, Zenodo, HAL, SSRN, Unpaywall (поиск по DOI) и опционально Sci-Hub.

• Стандартизированный вывод: Статьи возвращаются в едином формате словаря через класс Paper.

• Дизайн «сначала бесплатно»: Открытые и публичные источники имеют приоритет перед любыми опциональными коммерческими или ограниченными интеграциями.

• Опциональное улучшение с помощью API-ключей: Такие источники, как Semantic Scholar, могут работать лучше с пользовательским API-ключом, но не предназначены для принудительного платного использования.

• Рабочий процесс «обнаружение + извлечение»: Google Scholar и Crossref можно использовать для обнаружения и заполнения DOI, а открытые репозитории и ссылки издателей — для законного полнотекстового доступа, где это возможно.

• Цепочка запасных вариантов с приоритетом открытого доступа: download_with_fallback теперь использует: загрузка из исходного источника → обнаружение через OpenAIRE/CORE/Europe PMC/PMC → разрешение DOI через Unpaywall → опционально Sci-Hub.

• Интеграция с MCP: Совместим с MCP-клиентами для улучшения контекста LLM.

• Расширяемый дизайн: Легко добавлять новые академические платформы, расширяя модуль academic_platforms.

Стратегия источников

Долгосрочная цель — не зависеть от одной поисковой системы, а комбинировать несколько бесплатных и публичных источников с чёткими ролями:

• Открытая метаданная основа: Crossref, OpenAlex, Semantic Scholar, dblp, CiteSeerX, SSRN, Unpaywall (метаданные открытого доступа, ориентированные на DOI).

• Специализированные источники: arXiv, PubMed, PubMed Central, Europe PMC, IACR.

• Источники полнотекстового открытого доступа: arXiv, PMC, CORE, OpenAIRE, DOAJ, BASE, Zenodo, HAL, ссылки издателей на открытый доступ.

• Обнаружение и восстановление DOI: Google Scholar может быть полезен для поиска названий, версий и подсказок DOI, когда другие публичные источники метаданных неполны.

Рекомендуемая дорожная карта «сначала бесплатно»:

1. Поддерживать стабильность текущих публичных источников.

2. Добавить OpenAlex как широкий бесплатный источник метаданных.

3. Добавить PubMed Central и Europe PMC для более надёжного полнотекстового доступа к биомедицинским статьям.

4. Добавить CORE и OpenAIRE для извлечения открытого доступа из репозиториев.

5. Использовать Google Scholar в основном как запасной вариант для обнаружения, а не как основной канонический источник.

Матрица возможностей платформ

Эта матрица отражает проверенные результаты реальной интеграции из функциональных и сквозных регрессионных тестов в этом репозитории. Столбцы показывают максимальный уровень возможностей, наблюдаемый в нормальных условиях.

✅ = надёжно в реальных тестах. ⚠️ = работает, но подвержено нестабильности или ограничениям доступа вышестоящих систем. ❌ = не поддерживается. 🔑 = требуется ключ. 🚧 = только скелет.

Требования к учётным данным и API-ключам

Все ключи необязательны, если не указано иное. Настройте их в ~/.config/paper-search-mcp/.env (предпочтительно) или как переменные окружения оболочки.

Все переменные следуют схеме префикса PAPER_SEARCH_MCP_<NAME>. Устаревшие имена без префикса (например, CORE_API_KEY, UNPAYWALL_EMAIL) по-прежнему поддерживаются для обратной совместимости.

Известные ограничения внешних провайдеров

Некоторые сбои поиска вызваны нестабильностью внешних провайдеров, а не ошибками в этом проекте:

Необязательные платные коннекторы платформ (Фаза 3)

Коннекторы IEEE Xplore и ACM Digital Library включены как опциональные скелеты. Они отключены по умолчанию — никакие вызовы API не выполняются, если вы явно не настроите соответствующие ключи.

Как включить:

export PAPER_SEARCH_MCP_IEEE_API_KEY=<your_ieee_key>       # free key at https://developer.ieee.org/
export PAPER_SEARCH_MCP_ACM_API_KEY=<your_acm_key>         # see https://libraries.acm.org/digital-library

После установки ключа соответствующий источник автоматически добавляется в ALL_SOURCES, и его MCP-инструменты (search_ieee / search_acm, download_ieee / download_acm, read_ieee_paper / read_acm_paper) регистрируются при запуске сервера.

Без ключа коннекторы только записывают предупреждение при запуске — остальная часть сервера не затрагивается.

Расширение бесплатных источников (Фаза 4)

В MCP-сервер теперь интегрированы три дополнительных бесплатных коннектора:

• zenodo: Официальный коннектор REST API Zenodo (поиск + поддержка PDF/чтения, зависящая от записи).

• hal: Коннектор публичного API HAL (поиск + поддержка PDF/чтения, зависящая от записи).

• ssrn: Коннектор с приоритетом обнаружения, с усиленным парсером и загрузкой/чтением по возможности, когда доступна прямая публичная ссылка на PDF.

• unpaywall: Источник метаданных открытого доступа, ориентированный на DOI, для автономного поиска (search_unpaywall) и резолвинга URL-адресов.

Интеграция SSRN остаётся в первую очередь соответствующей требованиям: она пытается использовать только прямые публичные PDF-ссылки, доступные на страницах SSRN. Если требуется вход в систему или ограниченная доставка, коннектор возвращает понятное сообщение вместо обхода контроля доступа.

Уведомление о Sci-Hub

Поддержка Sci-Hub может оставаться доступной как необязательный коннектор для пользователей, которые явно решают его включить, но его не следует рассматривать как путь к полному тексту по умолчанию или рекомендуемый.

• Доступность нестабильна, зеркала часто меняются.

• Юридические и политические риски различаются в зависимости от юрисдикции.

• В README и описаниях инструментов должно быть чётко указано, что пользователи несут ответственность за его включение и использование.

• Источники открытого доступа и разрешённые издателем должны использоваться в первую очередь, когда это возможно.

Установка

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

Claude Code (навык) — рекомендуется для пользователей Claude Code

Установите как навык Claude Code вместо MCP-сервера. Это даёт Клоду автоматический доступ к поиску статей, когда вы упоминаете поиск статей, академическую литературу и т. д. — без необходимости настройки MCP.

Предварительные требования: uv и Claude Code.

Шаг 1 — Установите CLI:

uv tool install paper-search-mcp

Шаг 2 — Установите навык:

mkdir -p ~/.claude/skills/paper-search
curl -fsSL https://raw.githubusercontent.com/openags/paper-search-mcp/main/claude-code/SKILL.md \
  -o ~/.claude/skills/paper-search/SKILL.md

Шаг 3 (необязательно) — Настройте ключи API:

Создайте ~/.config/paper-search-mcp/.env для необязательных ключей API (см. Переменные окружения).

Всё. В следующий раз, когда вы запустите Claude Code, просто попросите его найти статьи — навык активируется автоматически. Например:

• "Найди мне недавние статьи о редактировании генома CRISPR"

• "Поищи в arxiv и semantic scholar механизмы внимания в трансформерах"

• "Скачай PDF для статьи arxiv 2106.12345"

Навык использует CLI (paper-search), который оборачивает ту же библиотеку, что и MCP-сервер, выводя JSON для поиска/загрузки и обычный текст для чтения.

Расположение файлов конфигурации MCP-сервера (для методов ниже)

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Метод 1 — Smithery (одна команда, рекомендуется для Claude Desktop)

npx -y @smithery/cli install @openags/paper-search-mcp --client claude

Smithery автоматически записывает правильный блок конфигурации. Ручное редактирование JSON не требуется.

Метод 2 — uvx (без установки, всегда последняя версия)

uvx запускает пакет напрямую из PyPI без постоянной установки. Требуется uv.

# Install uv (skip if already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

⚠️ Примечание для macOS: сгенерированные uvx обёрточные скрипты полагаются на realpath, который не входит в macOS по умолчанию. Если вы видите ошибку realpath: command not found, установите GNU coreutils (brew install coreutils) или используйте Метод 3 (uv run) — у него нет этого ограничения.

Конфигурация Claude Desktop:

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "uvx",
      "args": ["paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

Метод 3 — uv (постоянная установка)

uv tool install paper-search-mcp

Конфигурация Claude Desktop:

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "uv",
      "args": ["tool", "run", "paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

Метод 4 — pip (стандартная установка Python)

pip install paper-search-mcp

Конфигурация Claude Desktop:

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "python",
      "args": ["-m", "paper_search_mcp.server"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

Если python отсутствует в PATH, замените его полным путём (например, /usr/bin/python3 или C:\Python311\python.exe). Выполните which python3 / where python, чтобы найти его.

Метод 5 — npx (через Smithery CLI, без локального Python)

npx -y @smithery/cli run @openags/paper-search-mcp

Конфигурация Claude Desktop:

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "npx",
      "args": ["-y", "@smithery/cli", "run", "@openags/paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": ""
      }
    }
  }
}

Метод 6 — Docker

docker build -t paper-search-mcp .
docker run --rm -i \
  -e PAPER_SEARCH_MCP_UNPAYWALL_EMAIL=your@email.com \
  -e PAPER_SEARCH_MCP_CORE_API_KEY=your_core_key \
  paper-search-mcp

Конфигурация Claude Desktop:

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

Метод 7 — Клонирование и запуск из исходников (для разработки / рекомендуется для локального использования на macOS)

Это самый надёжный метод на macOS — без обёрточных скриптов и проблем с realpath.

# 1. Install uv (skip if already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Clone repo
git clone https://github.com/openags/paper-search-mcp.git
cd paper-search-mcp

# 3. Verify it runs (uv auto-resolves dependencies, no manual install needed)
uv run -m paper_search_mcp.server

Конфигурация Claude Desktop (замените путь к каталогу на фактическое место клонирования):

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/paper-search-mcp",
        "-m", "paper_search_mcp.server"
      ],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

Например, если вы клонировали в /Users/mac/Pengsong/paper-search-mcp:

"args": ["run", "--directory", "/Users/mac/Pengsong/paper-search-mcp", "-m", "paper_search_mcp.server"]

uv run автоматически устанавливает зависимости в изолированное окружение при первом запуске — не нужны pip install или venv.

Для активной разработки можно установить редактируемую копию:

uv venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Переменные окружения (файл .env)

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

mkdir -p ~/.config/paper-search-mcp
curl -fsSL https://raw.githubusercontent.com/openags/paper-search-mcp/main/.env.example \
  -o ~/.config/paper-search-mcp/.env
$EDITOR ~/.config/paper-search-mcp/.env

PAPER_SEARCH_MCP_UNPAYWALL_EMAIL=your@email.com
PAPER_SEARCH_MCP_CORE_API_KEY=
PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY=
PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN=
PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL=
PAPER_SEARCH_MCP_IEEE_API_KEY=
PAPER_SEARCH_MCP_ACM_API_KEY=

Чтобы использовать пользовательский путь: export PAPER_SEARCH_MCP_ENV_FILE=/absolute/path/to/.env

Устаревшие имена переменных без префикса PAPER_SEARCH_MCP_ (например, CORE_API_KEY, UNPAYWALL_EMAIL) по-прежнему поддерживаются для обратной совместимости.

Вклад в проект

Мы приветствуем вклад! Вот как начать:

1. Форкните репозиторий: Нажмите «Fork» на GitHub.

2. Клонируйте и настройте:

   git clone https://github.com/yourusername/paper-search-mcp.git
   cd paper-search-mcp
   uv venv && source .venv/bin/activate
   uv pip install -e ".[dev]"

3. Внесите изменения:

   • Добавляйте новые платформы в academic_platforms/.

   • Обновляйте тесты в tests/.

4. Отправьте pull request: Запушьте изменения и создайте PR на GitHub.

Демо

TODO

Планируемые академические платформы

• [√] arXiv

• [√] PubMed

• [√] bioRxiv

• [√] medRxiv

• [√] Google Scholar

• [√] IACR ePrint Archive

• [√] Semantic Scholar

• [√] Crossref

• [√] PubMed Central (PMC)

• [√] CORE

• [√] Europe PMC

• [√] Sci-Hub — документация по предупреждению и включению

Задачи разработки

• [√] Исправить ошибки асинхронного поиска и обеспечить надёжные быстрые события MCP

• [√] Скрипт сквозного тестирования полного конвейера (поиск, парсинг, загрузка)

• [√] Создать двухуровневую федеративную архитектуру (инструмент уровня 1: search_papers)

• [√] Обеспечить повсеместное извлечение DOI во всех полях метаданных и резервных вариантах аннотаций

• Граф цитирования и функция контекста связей между статьями

• [√] Расширить полнофункционального провайдера OpenAlex

Приоритетные бесплатные и открытые источники

• [√] PubMed Central (PMC)

• [√] CORE

• [√] OpenAlex

• [√] Europe PMC

• [√] OpenAIRE

• [√] dblp

• [√] CiteSeerX

• [√] DOAJ

• [√] BASE

• [√] Zenodo

• [√] HAL

• [√] SSRN (обнаружение + полный текст по мере возможности)

• [√] Unpaywall (автономный источник поиска по DOI)

Опциональные и неосновные интеграции

• ResearchGate

• JSTOR

• ScienceDirect

• Springer Link

• [√] IEEE Xplore (опциональный каркас — активируется с помощью IEEE_API_KEY)

• [√] ACM Digital Library (опциональный каркас — активируется с помощью ACM_API_KEY)

• Web of Science

• Scopus

История звёзд

Лицензия

Этот проект распространяется под лицензией MIT. Подробности см. в файле LICENSE.

Удачных исследований с paper-search-mcp! Если вы столкнулись с проблемами, откройте issue на GitHub.