Unpaywall MCP Server

Сервер MCP (Model Context Protocol), предоставляющий инструменты Unpaywall, чтобы ИИ-клиенты могли:

• Получать метаданные по DOI

• Искать по названиям статей

• Получать лучшие ссылки на полные тексты в открытом доступе (OA)

• Скачивать и извлекать текст из PDF в открытом доступе

Быстрый старт (npx)

Добавьте это в конфигурацию вашего MCP-клиента (пример для Claude Desktop):

{
  "mcpServers": {
    "unpaywall": {
      "command": "npx",
      "args": ["-y", "unpaywall-mcp"],
      "env": { "UNPAYWALL_EMAIL": "you@example.com" }
    }
  }
}

Затем попробуйте инструменты: unpaywall_search_titles, unpaywall_get_fulltext_links, unpaywall_fetch_pdf_text.

Вам не нужно клонировать этот репозиторий или запускать npm install — npx берет на себя загрузку и кэширование при первом вызове.

Related MCP server: ScholarScope MCP

Требования

• Node.js 18+ (для npx)

• Адрес электронной почты для запросов к Unpaywall / OpenAlex (требуется Unpaywall, используется для «вежливого пула» OpenAlex).

Локальная разработка (только для участников проекта)

Конечным пользователям следует использовать конфигурацию npx выше. Участники, собирающие проект из исходного кода:

npm install
npm run build
UNPAYWALL_EMAIL=you@example.com npm start   # stdio transport, as required by MCP clients

Горячий запуск (без этапа сборки):

UNPAYWALL_EMAIL=you@example.com npm run dev

Инструменты

unpaywall_get_by_doi

• Описание: Получение метаданных Unpaywall для DOI

• Схема входных данных:

  • doi (строка, обязательно): например, 10.1038/nphys1170

  • email (строка, опционально): переопределяет UNPAYWALL_EMAIL, если указан

• Выходные данные: JSON-ответ от Unpaywall

unpaywall_search_titles

• Описание: Поиск по названиям статей и возврат метаданных OA в стиле Unpaywall для каждого совпадения (50 результатов на страницу)

• Схема входных данных:

  • query (строка, обязательно): поисковый запрос по названию

  • is_oa (логическое, опционально): если true, только результаты в открытом доступе; если false, только закрытые; пропустите для всех

  • page (целое число >= 1, опционально): номер страницы

  • email (строка, опционально): переопределяет UNPAYWALL_EMAIL

• Выходные данные: JSON, соответствующий формату поиска Unpaywall — results[].response является записью в стиле DOI (doi, title, is_oa, oa_status, best_oa_location, oa_locations), с score и snippet для каждого результата. _source: "openalex" указывает на источник.

• Примечание: Работает на базе эндпоинта /works от OpenAlex, так как собственный /v2/search от Unpaywall возвращает HTTP 500 с момента обновления в мае 2025 года. Unpaywall теперь работает как подпрограмма OpenAlex, поэтому это канонический современный эквивалент.

unpaywall_get_fulltext_links

• Описание: Возврат лучшего URL PDF в открытом доступе и Open URL для DOI, а также всех локаций OA

• Схема входных данных:

  • doi (строка, обязательно)

  • email (строка, опционально): переопределяет UNPAYWALL_EMAIL

• Выходные данные: JSON с полями: best_pdf_url, best_open_url, best_oa_location, oa_locations и избранными метаданными

unpaywall_fetch_pdf_text

• Описание: Скачивание и извлечение текста из лучшего PDF в открытом доступе для DOI или из предоставленного pdf_url

• Схема входных данных:

  • pdf_url (строка, опционально): прямой URL PDF (имеет приоритет)

  • doi (строка, опционально): используется для определения лучшего PDF в открытом доступе, если pdf_url не предоставлен

  • email (строка, опционально): требуется при использовании doi и отсутствии переменной окружения UNPAYWALL_EMAIL

  • truncate_chars (целое число >= 1000, опционально): максимальное количество символов извлеченного текста для возврата (по умолчанию 20000)

• Выходные данные: JSON с text (возможно, обрезанным), length_chars, truncated, pdf_url и метаданными PDF

Советы по промптингу LLM (MCP)

При использовании этого сервера из LLM-клиента с поддержкой MCP, попросите модель:

• Сначала искать, потом получать: Используйте unpaywall_search_titles с кратким названием; выберите результат; затем вызовите unpaywall_get_fulltext_links или unpaywall_fetch_pdf_text для выбранного DOI.

• Предпочитать OA: Передавайте is_oa: true в поиске, если вам нужны только материалы в открытом доступе.

• Контролировать размер: Установите truncate_chars в unpaywall_fetch_pdf_text (по умолчанию 20000) и суммируйте длинные тексты перед продолжением.

• Быть устойчивой: Если лучший URL PDF отсутствует, переходите к best_open_url и извлекайте контент с целевой страницы (вне этого сервера).

• Соблюдать лимиты запросов: Делайте паузы между запросами, если их много; повторно используйте предыдущие ответы вместо повторения того же вызова.

Хорошие инструкции для LLM:

• "Найди 3 статьи в открытом доступе о 'фундаментальных моделях в биомедицине', затем извлеки и суммируй введение лучшей из них."

• "Найди 'обзор графовых нейронных сетей 2024', отфильтруй по открытому доступу, если возможно, затем получи текст PDF и сделай резюме из 10 пунктов."

Примеры полезной нагрузки вызова инструментов

В зависимости от вашего MCP-клиента структура может отличаться; основные полезные нагрузки:

// Search titles
{
  "name": "unpaywall_search_titles",
  "arguments": {
    "query": "graph neural networks survey",
    "is_oa": true,
    "page": 1
  }
}

// Get best OA links for a DOI
{
  "name": "unpaywall_get_fulltext_links",
  "arguments": {
    "doi": "10.48550/arXiv.1812.08434"
  }
}

// Fetch and extract PDF text (by DOI)
{
  "name": "unpaywall_fetch_pdf_text",
  "arguments": {
    "doi": "10.48550/arXiv.1812.08434",
    "truncate_chars": 20000
  }
}

Настройка в MCP-клиенте

Рекомендуемая конфигурация (без сборки) для Claude Desktop с использованием npm/npx:

{
  "mcpServers": {
    "unpaywall": {
      "command": "npx",
      "args": ["-y", "unpaywall-mcp"],
      "env": {
        "UNPAYWALL_EMAIL": "you@example.com"
      }
    }
  }
}

Альтернативная конфигурация (локальный репозиторий) с использованием скомпилированного dist:

{
  "mcpServers": {
    "unpaywall": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "UNPAYWALL_EMAIL": "you@example.com"
      }
    }
  }
}

После добавления попросите клиент вывести список инструментов и попробуйте:

• unpaywall_search_titles с параметром query

• unpaywall_get_fulltext_links с параметром doi

• unpaywall_fetch_pdf_text с параметром doi (или pdf_url)

Примечания

• Соблюдайте лимиты запросов и правила использования Unpaywall: https://unpaywall.org/products/api

• Сервер использует транспорт stdio и @modelcontextprotocol/sdk.

• Установите UNPAYWALL_EMAIL или передавайте email при каждом вызове, чтобы Unpaywall мог связаться с вами по поводу использования.

Сопровождающим: публикация в npm

# 1) Build the project (also runs automatically on publish)
npm run build

# 2) Bump version (choose patch/minor/major)
npm version patch

# 3) Publish (ensure you are logged in: npm login)
npm publish --access public

# 4) Tag a release on GitHub (optional, recommended)

Пользователи смогут настроить свой MCP-клиент с помощью npx -y unpaywall-mcp, как показано выше. Клонирование или сборка не требуются.