Semantic Scholar MCP Server

MCP-сервер Semantic Scholar с 14 инструментами для исследовательских задач. Прямой доступ к более чем 200 млн публикаций Semantic Scholar — поиск статей, обход графа цитирований, профили авторов и рекомендации — из любого клиента Model Context Protocol (Claude Desktop, Claude Code, Cursor, Cline, Continue и других).

Каждый релиз сопровождается проверяемым провенансом цепочки поставок: аттестациями SLSA build-provenance с подписью Sigstore для wheel, sdist и образа контейнера, аттестациями PEP 740 для загрузки в PyPI и SBOM в формате CycloneDX. Это позволяет доказать, что установленный вами артефакт собран именно из этого репозитория. Подробнее — в разделе «Провенанс и цепочка поставок».

Автор: Santiago Maniches · ORCID 0009-0005-6480-1987 · TOPOLOGICA LLC

Быстрый старт

uvx s2-mcp-server                                      # run instantly, no install
claude mcp add semantic-scholar -- uvx s2-mcp-server   # or register it in Claude Code

Для запуска API-ключ не нужен (публичное ограничение — 1 запрос/сек); задайте

SEMANTIC_SCHOLAR_API_KEY, чтобы получить 10 запросов/сек. Настройка для Claude Desktop, Docker, pip и

удалённого подключения (Streamable HTTP) описана в разделе «Установка».

Провенанс и цепочка поставок

Инструмент для исследований заслуживает доверия ровно настолько, насколько прозрачна цепочка от исходного

кода до запускаемого вами бинарного артефакта. Каждый релиз этого сервера сопровождается криптографически

проверяемыми свидетельствами цепочки поставок, которые формируются в CI из помеченного тегом коммита:

Гарантия	Что подтверждает	Где формируется
Провенанс сборки SLSA (wheel + sdist)	опубликованные дистрибутивы собраны workflow `publish.yml` из этого репозитория по тегу релиза, а не загружены вручную	`publish.yml` — `actions/attest-build-provenance` (задание `build`)
Провенанс сборки SLSA (образ контейнера)	дайджест образа в `ghcr.io` собран workflow `docker.yml` из этого репозитория	`docker.yml` — `actions/attest-build-provenance`, `push-to-registry` (строки 141–147)
Аттестации PEP 740	сама публикация в PyPI сопровождается аттестациями на базе Sigstore в рамках Trusted Publishing	`publish.yml` — `attestations: true` (задание `publish-pypi`)
CycloneDX SBOM	машиночитаемый перечень компонентов (bill of materials), формируемый в непривилегированном задании на основе статически разрешённых метаданных зависимостей конкретного wheel (только wheel, ничего не исполняется), привязанный к этому wheel по SHA-256 и затем аттестованный именно против него	`publish.yml` — `cyclonedx-py` + `scripts/release_sbom.py` (задание `sbom`) + `actions/attest-sbom` (задание `attest-sbom`)
Actions, закреплённые по SHA	каждое действие CI привязано к SHA коммита, поэтому сам конвейер релиза не может незаметно измениться	все задания в `.github/workflows/` (например, `publish.yml`, `docker.yml`)

Проверить wheel и образ контейнера по их аттестациям можно с помощью GitHub CLI:

# Wheel / sdist (download from the PyPI project or the release assets first)
gh attestation verify s2_mcp_server-*.whl --repo smaniches/semantic-scholar-mcp

# Container image
gh attestation verify oci://ghcr.io/smaniches/semantic-scholar-mcp:latest \
  --repo smaniches/semantic-scholar-mcp

Полное описание модели цепочки поставок, включая список известных ограничений, приведено в

SECURITY.md. Это провенанс на момент релиза (подтверждает,

как был собран артефакт); сейчас сервер не прикладывает отдельное подтверждение к каждому ответу API.

Сравнение

Публичного стандарта MCP для Semantic Scholar не существует, поэтому наиболее показательно сравнение с очевидной

альтернативой: самостоятельными вызовами Semantic Scholar REST API из

агента. Всё, что перечислено в правой колонке, — это инфраструктурная обвязка, которая уже реализована в этом сервере

и которую иначе пришлось бы писать вызывающей стороне заново.

	Этот сервер	Прямые вызовы S2 REST API из агента
Набор инструментов	14 типизированных инструментов MCP (поиск, извлечение, рекомендации, статус)	вызывающая сторона формирует HTTP-запросы вручную
Граф цитирований	оба направления (цитирования и ссылки) в `get_paper`	ручное постраничное обращение к двум эндпоинтам
Массовые операции	статьи (до 500) и авторы (до 1000) за один вызов	вызывающая сторона сама группирует и разбивает на страницы
Поиск по фрагментам полного текста	`snippet_search` с окружающим контекстом	отдельный эндпоинт, сборка на стороне вызывающего
Определение идентификатора статьи	семь форматов — Semantic Scholar ID, DOI, ArXiv, PubMed, Corpus ID, ACL, URL — с предварительной валидацией (`validators.py`)	вызывающая сторона сама нормализует и валидирует идентификаторы
Ограничение частоты запросов	клиентский лимитер по тарифам, интервал никогда не превышается (`client.py`)	вызывающая сторона регулирует вручную
Повторы и задержки	ограниченные повторы со случайным разбросом при 429/502/503/timeout, учитывается `Retry-After` (`client.py`)	вызывающая сторона реализует повторы сама
Ошибки	типизированная иерархия исключений, по которой вызывающая сторона может ветвиться (`errors.py`)	разбор строк HTTP-статусов
Вывод	Markdown, оптимизированный для чата, или JSON для каждого вызова (`formatters.py`)	сырой JSON
Провенанс цепочки поставок	SLSA + PEP 740 + CycloneDX SBOM для каждого релиза (см. выше)	н/д
Цитируемость	присвоенный DOI Zenodo, лицензия MIT	н/д

Установка

Вариант 1: установка одной командой (рекомендуется)

# No cloning needed — runs directly from PyPI
uvx s2-mcp-server

Вариант 2: Claude Code

claude mcp add semantic-scholar -- uvx s2-mcp-server

Вариант 3: Claude Desktop (Windows)

Добавьте в %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "semantic-scholar": {
      "command": "uvx",
      "args": ["s2-mcp-server"],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-key-here"
      }
    }
  }
}

Вариант 4: Claude Desktop (macOS)

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "semantic-scholar": {
      "command": "uvx",
      "args": ["s2-mcp-server"],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-key-here"
      }
    }
  }
}

Вариант 5: pip / из исходников

pip install s2-mcp-server
# or
git clone https://github.com/smaniches/semantic-scholar-mcp.git
cd semantic-scholar-mcp && pip install -e .

Вариант 6: Docker

docker pull ghcr.io/smaniches/semantic-scholar-mcp:latest
docker run -e SEMANTIC_SCHOLAR_API_KEY=your-key ghcr.io/smaniches/semantic-scholar-mcp

Вариант 7: удалённый сервер (Streamable HTTP) — требуется версия ≥ 1.5.0

# Serve MCP over HTTP at http://127.0.0.1:8000/mcp instead of stdio
# (--from pins the floor: uvx may otherwise reuse a cached older version)
uvx --from "s2-mcp-server>=1.5.0" s2-mcp-server --transport http

Настройка клиента, передача API-ключей для отдельных запросов и рекомендации по развёртыванию описаны в разделе

«Удалённый доступ (Streamable HTTP)».

Примечание. Бесплатный API-ключ можно получить на semanticscholar.org/product/api. Без ключа доступен публичный доступ с ограничением частоты (1 запрос/сек).

Архитектура

flowchart LR
  Client["MCP client<br/>(Claude Desktop, Claude Code,<br/>Cursor, Cline, Continue, …)"]
  subgraph Server ["s2-mcp-server (this package)"]
    direction TB
    FastMCP["FastMCP runtime<br/>(stdio / Streamable HTTP, lifespan)"]
    Tools["14 @mcp.tool functions<br/>(server.py)"]
    Models["Pydantic input models<br/>+ field sets (models.py)"]
    Validators["Paper-ID validator<br/>(validators.py)"]
    Cache["TTL cache<br/>(cache.py)"]
    Fmt["Markdown formatters<br/>(formatters.py)"]
    HTTP["httpx client<br/>+ rate limit + retry/backoff<br/>(client.py)"]
    Errors["Typed exceptions<br/>(errors.py)"]
    Log["Structured JSON logger<br/>(logging_config.py)"]
  end
  S2Graph["Semantic Scholar<br/>Graph API"]
  S2Recs["Semantic Scholar<br/>Recommendations API"]

  Client <-- "stdio or Streamable HTTP<br/>(JSON-RPC)" --> FastMCP
  FastMCP --> Tools
  Tools --> Models
  Tools --> Validators
  Tools --> Cache
  Tools --> HTTP
  Tools --> Fmt
  HTTP --> Errors
  HTTP --> Log
  HTTP -- "GET / POST<br/>x-api-key" --> S2Graph
  HTTP -- "GET / POST<br/>x-api-key" --> S2Recs

Зоны ответственности модулей (src/semantic_scholar_mcp/):

Модуль	Зона ответственности
`server.py`	Экземпляр FastMCP, 14 регистраций `@mcp.tool`, lifespan, точка входа `main()`. Реэкспортирует вспомогательные функции для обратной совместимости.
`transport.py`	Транспорт Streamable HTTP: разбор CLI/переменных окружения (`--transport http`), подключение uvicorn и извлечение API-ключа для каждого запроса (заголовок / query-параметр / конфигурация Smithery) в contextvar, привязанный к запросу.
`client.py`	Общий singleton `httpx.AsyncClient`, ограничитель скорости для каждого уровня (1 запрос/с публично, 10 запросов/с с ключом), цикл повторных попыток с экспоненциальной задержкой и джиттером при 429/502/503/timeout, сопоставление HTTP-ошибок с типизированными исключениями.
`models.py`	Pydantic-модели входных данных для каждого инструмента, enum `ResponseFormat`, четыре константы наборов полей по уровням (`PAPER_SEARCH_FIELDS`, `…_LITE`, `PAPER_BULK_SEARCH_FIELDS`, `PAPER_DETAIL_FIELDS`, `AUTHOR_FIELDS`).
`validators.py`	Предварительная валидация paper-ID. Отклоняет NUL-байты, `?`, `#`, path traversal; принимает семь канонических форматов ID.
`cache.py`	TTL-кэш в памяти (5 мин, 200 записей, вытеснение сначала старых) для поиска статей/авторов в рамках сессии.
`formatters.py`	Markdown-рендереры для словарей статей и авторов, оптимизированные для читаемости в чат-интерфейсе.
`errors.py`	Иерархия `SemanticScholarError`: `AuthenticationError`, `RateLimitError`, `NotFoundError`, `ValidationError`, `ServerError`.
`logging_config.py`	`StructuredFormatter` с одним JSON на строку в stderr; безопасно передавать через любой агрегатор логов.

Проектные решения, которые стоит знать

Единственный httpx.AsyncClient на процесс. Создаётся лениво, закрывается при завершении lifespan FastMCP. Амортизирует установку соединений; учитывает лимиты keep-alive. Lifespan использует подсчёт ссылок: при транспорте Streamable HTTP SDK входит в него на каждый запрос, поэтому завершение выполняется только когда выходит последний держатель.
Ограничение скорости применяется на клиенте, а не на стороне API. Семафор и временная метка последнего запроса гарантируют, что мы не превысим интервал для соответствующего уровня, даже если MCP-хост параллельно вызывает инструменты.
Повторные попытки ограничены и имеют джиттер. До MAX_RETRIES = 3, базой 1 с, максимум 30 с. Учитывает Retry-After, если он есть.
Ошибки типизированы. Коды статусов сопоставляются с небольшой иерархией исключений, чтобы вызывающий код мог различать AuthenticationError, RateLimitError и NotFoundError, а не разбирать строки.
Валидация входных данных выполняется предварительно. Идентификаторы статей проверяются до любого исходящего запроса; некорректные ID никогда не попадают в сеть.
Версия задаётся в одном месте. __version__ берётся из importlib.metadata.version("s2-mcp-server"), поэтому достаточно обновить pyproject.toml; release-please синхронно обновляет манифест, server.json (2 пути), CITATION.cff и .zenodo.json при каждом релизе.

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

Варианты API-ключа

API-ключ можно указать тремя способами:

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

export SEMANTIC_SCHOLAR_API_KEY="your-api-key-here"

HTTP-заголовок для каждого запроса (только для транспорта Streamable HTTP): отправляйте

x-api-key: your-key с каждым запросом — см.

раздел «Удалённый доступ (Streamable HTTP)».

Параметр для каждого запроса (переопределяет переменную окружения):

{
  "api_key": "your-api-key-here"
}

Устарело: параметр api_key для каждого запроса устарел и будет удалён в v2.0.0. Аргументы вызова инструментов могут быть видны в MCP-транскриптах, логах клиента и истории вызовов инструментов LLM. Вместо него используйте переменную окружения SEMANTIC_SCHOLAR_API_KEY. Подробности см. в SECURITY.md.

Получите бесплатный API-ключ здесь: https://www.semanticscholar.org/product/api

Настройка Claude Desktop

Добавьте в конфигурационный файл Claude Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json

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

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

{
  "mcpServers": {
    "semantic-scholar": {
      "command": "python",
      "args": ["-m", "semantic_scholar_mcp"],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-api-key-here"
      }
    }
  }
}

Затем перезапустите Claude Desktop.

Удалённый доступ (Streamable HTTP)

stdio остаётся транспортом по умолчанию. --transport http обслуживает те же 14

инструментов через транспорт MCP Streamable HTTP,

к которому подключаются удалённые клиенты — пользовательские коннекторы claude.ai, листинги Smithery,

мосты mcp-remote.

Требуется s2-mcp-server ≥ 1.5.0. Более ранние версии (≤ 1.4.0) не разбирают флаги CLI: они молча игнорируют --transport http и вместо этого запускают stdio-сервер, никогда не открывая порт.

# Local HTTP endpoint at http://127.0.0.1:8000/mcp
# (--from pins the floor: uvx may otherwise reuse a cached older version)
uvx --from "s2-mcp-server>=1.5.0" s2-mcp-server --transport http

# Bind a public interface and custom port (only behind a TLS proxy — see Security)
uvx --from "s2-mcp-server>=1.5.0" s2-mcp-server --transport http --host 0.0.0.0 --port 8080

# Docker
docker run -p 8000:8000 ghcr.io/smaniches/semantic-scholar-mcp --transport http

Флаги и переменные окружения

Флаг	Переменная окружения	Значение по умолчанию	Описание
`--transport`	`MCP_TRANSPORT`	`stdio`	`stdio`, `http` (псевдоним: `streamable-http`)
`--host`	`MCP_HOST`	`127.0.0.1`	Адрес привязки (`0.0.0.0` в Docker-образе)
`--port`	`MCP_PORT`, затем `PORT`	`8000`	Порт привязки (`PORT` учитывается для хостинговых платформ)
`--path`	`MCP_PATH`	`/mcp`	URL-путь конечной точки MCP
—	`MCP_STATELESS_HTTP`	`true`	Одно независимое взаимодействие с сервером на запрос (рекомендуется)
—	`MCP_JSON_RESPONSE`	`true`	Обычные JSON-ответы вместо потоков SSE

Флаги CLI имеют приоритет над переменными окружения. Сервер не хранит состояние и по умолчанию возвращает

JSON — эта конфигурация рекомендуется для production-развёртываний Streamable

HTTP — и ни один инструмент не зависит от сессий, стриминга или

сообщений, инициируемых сервером, поэтому функционального компромисса нет.

API-ключи для каждого запроса (собственный ключ)

При работе через HTTP каждый запрос может нести собственный API-ключ Semantic Scholar;

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

порядке приоритета:

HTTP-заголовок x-api-key (рекомендуется)
query-параметр SEMANTIC_SCHOLAR_API_KEY (конфигурация сессии Smithery)
query-параметр api_key
Устаревший base64-параметр ?config= (старые развёртывания Smithery)

Запрос без ключа использует резервную переменную окружения сервера SEMANTIC_SCHOLAR_API_KEY

или доступ без ключа на публичном уровне.

Конфигурация клиента

Claude Code

claude mcp add --transport http semantic-scholar http://127.0.0.1:8000/mcp \
  --header "x-api-key: your-key-here"

JSON-конфигурация (клиенты, принимающие url)

{
  "mcpServers": {
    "semantic-scholar": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": { "x-api-key": "your-key-here" }
    }
  }
}

Пользовательские коннекторы claude.ai требуют публичный HTTPS URL и поддерживают либо серверы без аутентификации, либо OAuth. API-ключи в URL коннектора не поддерживаются claude.ai. Разместите сервер с ключом, заданным на стороне сервера (переменная окружения SEMANTIC_SCHOLAR_API_KEY), и зарегистрируйте публичный URL /mcp как коннектор.

Smithery публикует список удалённых серверов по URL (smithery mcp publish ); описанное выше извлечение ключа для каждого запроса совместимо с конфигурацией сессии Smithery без дополнительной настройки.

Замечания по безопасности

HTTP-транспорт не выполняет аутентификацию входящих клиентов. По умолчанию привязка выполняется к loopback (127.0.0.1). Открывайте его публично только за обратным прокси, терминирующим TLS, и предпочитайте заголовок x-api-key параметрам запроса (URL попадают в журналы доступа).
API-ключи действуют в пределах запроса, и сам сервер никогда не записывает их в журналы. (Ключ, помещённый в параметр запроса URL, всё ещё может попасть в журналы доступа, как отмечено выше, — предпочитайте заголовок x-api-key.)
См. SECURITY.md для более широкой модели угроз проекта.

Поддерживаемые форматы идентификаторов

Сервер принимает следующие форматы идентификаторов статей:

Формат	Шаблон	Пример
Semantic Scholar ID	40-символьная шестнадцатеричная строка	`649def34f8be52c8b66281af98ae884c09aef38b`
DOI	`DOI:xxx`	`DOI:10.1038/s41586-021-03819-2`
ArXiv	`ARXIV:xxx`	`ARXIV:2106.15928` или `ARXIV:2106.15928v2`
PubMed	`PMID:xxx`	`PMID:32908142`
Corpus ID	`CorpusId:xxx`	`CorpusId:215416146`
ACL	`ACL:xxx`	`ACL:P19-1285`
URL	`URL:xxx`	`URL:https://arxiv.org/abs/2106.15928`

Справочник по инструментам

1. `semantic_scholar_search_papers`

Поиск научных статей с расширенными фильтрами.

Параметры:

Параметр	Тип	Обязательный	Описание
`query`	string	Да	Поисковый запрос (поддерживает операторы AND, OR, NOT и «фразовый поиск»)
`year`	string	Нет	Фильтр по году: `"2024"`, `"2020-2024"` или `"2020-"`
`fields_of_study`	string[]	Нет	Фильтр по областям: `["Computer Science", "Biology"]`
`publication_types`	string[]	Нет	Фильтр по типу: `["Review", "JournalArticle"]`
`open_access_only`	boolean	Нет	Возвращать только статьи в открытом доступе (по умолчанию: false)
`min_citation_count`	integer	Нет	Минимальное число цитирований
`limit`	integer	Нет	Максимум результатов 1–100 (по умолчанию: 10)
`offset`	integer	Нет	Смещение для пагинации (по умолчанию: 0)
`response_format`	string	Нет	`"markdown"` или `"json"` (по умолчанию: markdown)
`api_key`	string	Нет	Переопределить API-ключ из окружения

Пример:

Search for "transformer attention mechanism" papers from 2023 with at least 100 citations

Пример JSON:

{
  "query": "transformer attention mechanism",
  "year": "2023",
  "min_citation_count": 100,
  "fields_of_study": ["Computer Science"],
  "limit": 20
}

2. `semantic_scholar_get_paper`

Получение подробной информации о конкретной статье.

Параметры:

Параметр	Тип	Обязательный	Описание
`paper_id`	string	Да	ID статьи в любом поддерживаемом формате
`include_citations`	boolean	Нет	Включать цитирующие статьи (по умолчанию: false)
`include_references`	boolean	Нет	Включать статьи из списка литературы (по умолчанию: false)
`citations_limit`	integer	Нет	Максимум цитирований для возврата 1–100 (по умолчанию: 10)
`references_limit`	integer	Нет	Максимум ссылок для возврата 1–100 (по умолчанию: 10)
`response_format`	string	Нет	`"markdown"` или `"json"` (по умолчанию: markdown)
`api_key`	string	Нет	Переопределить API-ключ из окружения

Пример:

Get details for DOI:10.1038/s41586-021-03819-2 including its top 20 citations

Пример JSON:

{
  "paper_id": "DOI:10.1038/s41586-021-03819-2",
  "include_citations": true,
  "citations_limit": 20
}

3. `semantic_scholar_search_authors`

Поиск научных авторов по имени.

Параметры:

Параметр	Тип	Обязательный	Описание
`query`	string	Да	Имя автора для поиска
`limit`	integer	Нет	Максимум результатов 1–100 (по умолчанию: 10)
`offset`	integer	Нет	Смещение для пагинации (по умолчанию: 0)
`response_format`	string	Нет	`"markdown"` или `"json"` (по умолчанию: markdown)
`api_key`	string	Нет	Переопределить API-ключ из окружения

Пример:

Find author "Yoshua Bengio"

Пример JSON:

{
  "query": "Yoshua Bengio",
  "limit": 5
}

4. `semantic_scholar_get_author`

Получение профиля автора с публикациями.

Параметры:

Параметр	Тип	Обязательный	Описание
`author_id`	string	Да	ID автора в Semantic Scholar
`include_papers`	boolean	Нет	Включать публикации (по умолчанию: true)
`papers_limit`	integer	Нет	Максимум статей для возврата 1–100 (по умолчанию: 20)
`response_format`	string	Нет	`"markdown"` или `"json"` (по умолчанию: markdown)
`api_key`	string	Нет	Переопределить API-ключ из окружения

Пример:

Get author profile for author ID 1741101 with their top 50 publications

Пример JSON:

{
  "author_id": "1741101",
  "include_papers": true,
  "papers_limit": 50
}

5. `semantic_scholar_recommendations`

Получение рекомендаций статей на основе ИИ по исходной статье.

Параметры:

Параметр	Тип	Обязательный	Описание
`paper_id`	string	Да	ID исходной статьи в любом поддерживаемом формате
`from_pool`	string	Нет	Пул рекомендаций: `"recent"` (по умолчанию) или `"all-cs"`
`limit`	integer	Нет	Максимум рекомендаций 1–100 (по умолчанию: 10)
`response_format`	string	Нет	`"markdown"` или `"json"` (по умолчанию: markdown)
`api_key`	string	Нет	Переопределить API-ключ из окружения

Пример:

Get recommendations based on paper 649def34f8be52c8b66281af98ae884c09aef38b

Пример JSON:

{
  "paper_id": "ARXIV:1706.03762",
  "limit": 15
}

6. `semantic_scholar_bulk_papers`

Получение нескольких статей одним запросом (максимум 500).

Параметры:

Параметр	Тип	Обязательный	Описание
`paper_ids`	string[]	Да	Список ID статей (максимум 500)
`response_format`	string	Нет	`"markdown"` или `"json"` (по умолчанию: json)
`api_key`	string	Нет	Переопределить API-ключ из окружения

Пример:

Retrieve these papers: DOI:10.1038/nature12373, ARXIV:2106.15928, PMID:32908142

Пример JSON:

{
  "paper_ids": [
    "DOI:10.1038/nature12373",
    "ARXIV:2106.15928",
    "PMID:32908142"
  ]
}

7. `semantic_scholar_bulk_search`

Поиск статей с сортировкой и пагинацией на основе курсора для больших наборов результатов.

В отличие от search_papers, поддерживает сортировку sort и возвращает token для постраничного просмотра всех результатов.

Параметры:

Параметр	Тип	Обязательный	Описание
`query`	string	Да	Поисковый запрос
`sort`	string	Нет	Порядок сортировки, например `"citationCount:desc"`, `"publicationDate:asc"`
`token`	string	Нет	Токен продолжения из предыдущего ответа bulk_search
`year`	string	Нет	Фильтр по году: `"2024"`, `"2020-2024"`, `"2020-"`
`fields_of_study`	string[]	Нет	Фильтр по областям: `["Computer Science"]`
`publication_types`	string[]	Нет	Фильтр по типу: `["Review", "JournalArticle"]`
`min_citation_count`	integer	Нет	Минимальное число цитирований
`limit`	integer	Нет	Максимум результатов на страницу 1–1000 (по умолчанию: 100)
`response_format`	string	Нет	`"markdown"` или `"json"` (по умолчанию: markdown)
`api_key`	string	Нет	Переопределить API-ключ из окружения

Пример JSON:

{
  "query": "graph neural networks",
  "sort": "citationCount:desc",
  "year": "2020-2024",
  "limit": 100
}

Возвращает: общее число результатов, страницу статей и token для следующей страницы (если есть дополнительные результаты).

8. `semantic_scholar_export_citation`

Экспорт библиографической ссылки на статью в формате BibTeX.

Параметры:

Параметр	Тип	Обязательный	Описание
`paper_id`	string	Да	ID статьи в любом поддерживаемом формате
`format`	string	Нет	Формат цитирования (сейчас только `"bibtex"`)
`api_key`	string	Нет	Переопределить API-ключ из окружения

Пример JSON:

{
  "paper_id": "DOI:10.1038/s41586-021-03819-2",
  "format": "bibtex"
}

Возвращает: строку BibTeX для запрошенной статьи.

9. `semantic_scholar_match_paper`

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

Параметры:

Параметр	Тип	Обязательный	Описание
`query`	string	Да	Заголовок статьи для сопоставления (1–500 символов)
`response_format`	string	Нет	`"markdown"` или `"json"` (по умолчанию: markdown)
`api_key`	string	Нет	Переопределяет API-ключ из переменных окружения

Пример JSON:

{
  "query": "Attention Is All You Need"
}

Возвращает: наиболее подходящую статью и её matchScore, либо сообщение "No matching paper found.", если совпадений нет.

10. `semantic_scholar_paper_authors`

Возвращает полные профили всех авторов статьи (более подробные, чем сокращённый список авторов, который возвращает get_paper).

Параметры:

Параметр	Тип	Обязательный	Описание
`paper_id`	string	Да	Идентификатор статьи в любом поддерживаемом формате
`limit`	integer	Нет	Максимум авторов в ответе: 1–1000 (по умолчанию: 100)
`response_format`	string	Нет	`"markdown"` или `"json"` (по умолчанию: markdown)
`api_key`	string	Нет	Переопределяет API-ключ из переменных окружения

Пример JSON:

{
  "paper_id": "ARXIV:1706.03762",
  "limit": 25
}

Возвращает: список полных записей об авторах статьи.

11. `semantic_scholar_author_batch`

Получает данные сразу нескольких авторов в рамках одного запроса (до 1000).

Параметры:

Параметр	Тип	Обязательный	Описание
`author_ids`	string[]	Да	Список идентификаторов авторов (1–1000)
`response_format`	string	Нет	`"markdown"` или `"json"` (по умолчанию: json)
`api_key`	string	Нет	Переопределяет API-ключ из переменных окружения

Пример JSON:

{
  "author_ids": ["1741101", "40348417", "144749327"]
}

Возвращает: счётчики requested / retrieved, полученные записи об авторах, а также список not_found с идентификаторами, которые API не вернул.

12. `semantic_scholar_multi_recommend`

Строит рекомендации на основе нескольких положительных (и при необходимости отрицательных) статей-примеров.

Параметры:

Параметр	Тип	Обязательный	Описание
`positive_paper_ids`	string[]	Да	Статьи, для которых нужно найти похожие (1–100)
`negative_paper_ids`	string[]	Нет	Статьи, которые следует исключать из рекомендаций (0–100)
`limit`	integer	Нет	Максимум рекомендаций: 1–500 (по умолчанию: 10)
`response_format`	string	Нет	`"markdown"` или `"json"` (по умолчанию: markdown)
`api_key`	string	Нет	Переопределяет API-ключ из переменных окружения

Пример JSON:

{
  "positive_paper_ids": ["ARXIV:1706.03762", "ARXIV:1810.04805"],
  "negative_paper_ids": ["DOI:10.1038/nature14539"],
  "limit": 20
}

Возвращает: рекомендованные статьи, а также эхо-повтор использованных положительных и отрицательных seed-статей.

13. `semantic_scholar_snippet_search`

Выполняет поиск по полному тексту статей и возвращает текстовые фрагменты с окружающим контекстом. Без API-ключа действуют жёсткие ограничения частоты запросов.

Параметры:

Параметр	Тип	Обязательный	Описание
`query`	string	Да	Поисковый запрос по тексту статей (1–500 символов)
`paper_ids`	string[]	Нет	Ограничить поиск указанными статьями (не более 100)
`year`	string	Нет	Фильтр по году: `"2024"`, `"2020-2024"`, `"2020-"`
`fields_of_study`	string[]	Нет	Фильтр по областям знания: `["Computer Science"]`
`min_citation_count`	integer	Нет	Минимальное количество цитирований
`limit`	integer	Нет	Максимум результатов: 1–100 (по умолчанию: 10)
`response_format`	string	Нет	`"markdown"` или `"json"` (по умолчанию: markdown)
`api_key`	string	Нет	Переопределяет API-ключ из переменных окружения

Пример JSON:

{
  "query": "scaling laws for language models",
  "year": "2022-2024",
  "limit": 20
}

Возвращает: найденные фрагменты; каждый из них содержит название исходной статьи, раздел и короткую выдержку из текста.

14. `semantic_scholar_status`

Проверяет работоспособность сервера и доступность API.

Параметры: отсутствуют

Пример:

Check Semantic Scholar API status

Ответ:

{
  "server": "semantic-scholar-mcp",
  "version": "<current package version>",
  "api_key_configured": true,
  "rate_tier": "authenticated (10 req/sec)",
  "timestamp": "2026-04-06T12:00:00.000000+00:00",
  "api_reachable": true,
  "rate_limited": false,
  "retry_after": null
}

Лимиты запросов

Уровень	Запросов/секунду	Как получить
Без API-ключа	1 запрос/сек	По умолчанию
API-ключ	10 запросов/сек	Регистрация (бесплатно)
Академический партнёр	10–100 запросов/сек	Заявка через S2

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

Сервер автоматически справляется с лимитами частоты запросов:

Сериализация запросов для соблюдения минимальных интервалов между ними
Повторные попытки с экспоненциальной задержкой при ошибках 429 (превышение лимита запросов), 502 (ошибка шлюза) и 503 (сервис недоступен)
Максимум 3 повторные попытки с добавлением джиттера

Разработка

# Clone
git clone https://github.com/smaniches/semantic-scholar-mcp.git
cd semantic-scholar-mcp

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/semantic_scholar_mcp --cov-report=term-missing

# Type checking
mypy src/

Безопасность

Сервер никогда не сохраняет API-ключи на диск. При выполнении аутентифицированных запросов ключ передаётся только на api.semanticscholar.org по HTTPS в заголовке x-api-key. Никакая телеметрия не отправляется третьим сторонам. При использовании транспорта stdio (по умолчанию) сервер работает локально на вашей машине; если же вы подключаетесь к размещённому удалённо экземпляру через Streamable HTTP, ключ каждого запроса дополнительно проходит через оператора этого эндпоинта, прежде чем будет переслан в Semantic Scholar. Отправляйте ключи только на те удалённые эндпоинты, которым доверяете, и только по HTTPS.

Отдавайте предпочтение переменной окружения SEMANTIC_SCHOLAR_API_KEY, а не параметру api_key, передаваемому при каждом вызове инструмента. Такой per-request параметр устарел (его удаление запланировано в версии v2.0.0), поскольку аргументы вызовов инструментов могут попадать в MCP-транскрипты и логи клиента. О том, как сообщать об уязвимостях, а также о списке известных ограничений читайте в SECURITY.md.

Другие MCP-серверы того же автора

alphafold-sovereign-mcp — сервер Model Context Protocol для AlphaFold DB и других открытых биомедицинских источников данных с локальным графом знаний на SQLite (pip install alphafold-sovereign-mcp).
uniprot-mcp — сервер Model Context Protocol для UniProt Swiss-Prot и TrEMBL (pip install uniprot-mcp-server).

Лицензия

Лицензия MIT — см. файл LICENSE.

Автор

Santiago Maniches

Основатель и CEO, TOPOLOGICA LLC
ORCID: 0009-0005-6480-1987
LinkedIn: santiago-maniches
Сайт: topologica.ai

Участие в разработке

Ваш вклад приветствуется! Пожалуйста, ознакомьтесь с нашими правилами участия в разработке.

Поддержка

Баг-репорты и предложения: GitHub Issues
Контакты: santiago@topologica.ai

Разработано TOPOLOGICA LLC

Semantic Scholar MCP Server

Быстрый старт

Провенанс и цепочка поставок

Сравнение

Установка

Вариант 1: установка одной командой (рекомендуется)

Вариант 2: Claude Code

Вариант 3: Claude Desktop (Windows)

Вариант 4: Claude Desktop (macOS)

Вариант 5: pip / из исходников

Вариант 6: Docker

Вариант 7: удалённый сервер (Streamable HTTP) — требуется версия ≥ 1.5.0

Архитектура

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

Варианты API-ключа

Настройка Claude Desktop

Удалённый доступ (Streamable HTTP)

Флаги и переменные окружения

API-ключи для каждого запроса (собственный ключ)

Конфигурация клиента

Замечания по безопасности

Поддерживаемые форматы идентификаторов

Справочник по инструментам

1. semantic_scholar_search_papers

2. semantic_scholar_get_paper

3. semantic_scholar_search_authors

4. semantic_scholar_get_author

5. semantic_scholar_recommendations

6. semantic_scholar_bulk_papers

7. semantic_scholar_bulk_search

8. semantic_scholar_export_citation

9. semantic_scholar_match_paper

10. semantic_scholar_paper_authors

11. semantic_scholar_author_batch

12. semantic_scholar_multi_recommend

13. semantic_scholar_snippet_search

14. semantic_scholar_status

Лимиты запросов

Разработка

Безопасность

Другие MCP-серверы того же автора

Лицензия

Автор

Участие в разработке

Поддержка

1. `semantic_scholar_search_papers`

2. `semantic_scholar_get_paper`

3. `semantic_scholar_search_authors`

4. `semantic_scholar_get_author`

5. `semantic_scholar_recommendations`

6. `semantic_scholar_bulk_papers`

7. `semantic_scholar_bulk_search`

8. `semantic_scholar_export_citation`

9. `semantic_scholar_match_paper`

10. `semantic_scholar_paper_authors`

11. `semantic_scholar_author_batch`

12. `semantic_scholar_multi_recommend`

13. `semantic_scholar_snippet_search`

14. `semantic_scholar_status`