SemanticScholar_MCP

Semantic Scholar API의 세 가지 패밀리를 위한 결정적 Model Context Protocol 인터페이스입니다:

• S2AG — Academic Graph 검색, 메타데이터, 저자, 인용 및 참고문헌.

• Recommendations — Semantic Scholar의 논문 추천 서비스.

• Datasets — 릴리스 검색, 데이터셋 매니페스트, 증분 데이터셋 업데이트.

이 프로젝트는 의도적으로 에이전트형 문헌 연구 시스템이 아닌 얇은 API 래퍼를 제공합니다.

설계

핵심 규칙은 다음과 같습니다:

MCP 도구 호출 하나는 문서화된 Semantic Scholar 작업 하나를 나타냅니다.

서버는 검증, 인증, 속도 제한, 재시도, 응답 정규화와 같은 전송 수준 작업을 수행합니다.

서버는 어떤 문헌이 과학적으로 중요한지 결정하지 않습니다.

예를 들어:

Agent
  │
  ├── "Search for paired-pulse TMS papers"
  │         │
  │         ▼
  │       S2AG MCP
  │         │
  │         ▼
  │    Semantic Scholar
  │
  ├── "Recommend papers from these three seed papers"
  │         │
  │         ▼
  │  Recommendations MCP
  │         │
  │         ▼
  │    Semantic Scholar
  │
  └── "Describe the latest S2ORC dataset release"
            │
            ▼
       Datasets MCP
            │
            ▼
       Semantic Scholar

검색 확장, 과학적 해석, 요약, 인용 그래프 탐색 전략, 연구 종합은 소비 에이전트의 책임으로 남습니다.

Related MCP server: Semantic Scholar MCP Server

저장소 구조

SemanticScholar_MCP/
├── src/
│   └── semantic_scholar_mcp/
│       ├── common/
│       │   ├── client.py
│       │   ├── errors.py
│       │   ├── models.py
│       │   ├── rate_limit.py
│       │   └── __init__.py
│       ├── datasets/
│       │   ├── server.py
│       │   └── __init__.py
│       ├── recommendations/
│       │   ├── server.py
│       │   └── __init__.py
│       ├── s2ag/
│       │   ├── server.py
│       │   └── __init__.py
│       └── __init__.py
├── tests/
├── AGENTS.md
├── CLAUDE.md
├── pyproject.toml
└── README.md

요구 사항

• Python 3.11 이상

• Semantic Scholar에 대한 인터넷 접근

• 선택 사항: Semantic Scholar API 키

구현은 공식 Python MCP SDK의 현재 v2 라인을 사용합니다.

설치

가상 환경을 생성합니다:

py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1

개발 의존성과 함께 패키지를 편집 가능 모드로 설치합니다:

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

또는 uv를 사용하는 경우:

uv venv --python 3.14
uv pip install -e ".[dev]"

Python 3.14는 필요하지 않습니다. 이 프로젝트는 Python 3.11 이상을 지원합니다.

Python 패키지 환경을 구성한 후, 선택적으로 테스트를 실행합니다:

pytest
ruff check .
ruff format --check .

이미 SEMANTIC_SCHOLAR_API_KEY를 시스템 환경 변수로 구성했다면(다음 섹션 인증 참조), 라이브 통합도 테스트할 수 있습니다:

pytest --run-integration

참고: 시스템 환경 변수를 API 키로 설정한 시점이 어떤 VSCode 창을 시작한 후라면, VSCode Extensions를 통해 실행되는 도구가 시스템 환경을 인식하도록 하려면 모든 VSCode 창을 닫아 VSCode를 완전히 다시 시작해야 합니다!

인증

Semantic Scholar는 많은 API 작업에 대해 인증되지 않은 접근을 지원합니다.

API 키를 사용할 수 있는 경우, 다음을 통해 MCP 프로세스에 노출하십시오:

$env:SEMANTIC_SCHOLAR_API_KEY = "..."

키를 다음 위치에 두지 마십시오:

• .mcp.json;

• .codex/config.toml;

• 소스 코드;

• 커밋된 .env 파일;

• 테스트 픽스처.

MCP 서버는 키가 존재하면 자동으로 사용합니다.

인증이 필요한 작업은 키가 구성되지 않은 경우 명시적 오류를 반환해야 합니다.

(다시) 참고: 시스템 환경 변수를 API 키로 설정한 시점이 어떤 VSCode 창을 시작한 후라면, VSCode Extensions를 통해 실행되는 도구가 시스템 환경을 인식하도록 하려면 모든 VSCode 창을 닫아 VSCode를 완전히 다시 시작해야 합니다!

빌드 업데이트

.\rebuild.ps1 및 .\version.ps1 스크립트는 리빌드 시 버전 업데이트를 돕는 유틸리티로 제공됩니다:

rebuild.ps1

patch 번호를 자동 증가시키지 않고 리빌드하려면 스위치를 명시적으로 지정하십시오:

.\rebuild.ps1 -SkipVersionIncrement

그렇지 않으면 .\rebuild.ps1이 pyproject.toml의 patch 번호를 직접 자동 증가시킵니다.

version.ps1

리빌드 없이 <major> | <minor> | <patch>를 증가시키려면:

.\version.ps1 patch -NoRebuild

minor 버전을 증가시키고 patch를 0으로 초기화한 후 리빌드하려면:

.\version.ps1 minor

major 버전을 증가시키고 minor와 patch를 모두 0으로 초기화한 후 리빌드하려면:

.\version.ps1 major

MCP 클라이언트 구성

세 가지 Semantic Scholar MCP 서버는 다음 중 하나로 구성할 수 있습니다:

• 프로젝트 로컬(project-local) — 특정 저장소 내에서만 사용 가능

• 사용자 전역(user-global) — 저장소에 걸쳐 사용 가능

서버는 다음과 같습니다:

• s2ag — Semantic Scholar Academic Graph

• s2_recommendations — Semantic Scholar Recommendations API

• s2_datasets — Semantic Scholar Datasets API

아래 예시는 이 저장소가 다음 위치에 설치되어 있다고 가정합니다:

C:\MyRepos\Python\SemanticScholar_MCP

필요에 따라 경로를 조정하십시오.

예시는 의도적으로 생성된 semantic-scholar-*.exe 콘솔 런처를 직접 호출하는 대신 가상 환경의 Python 인터프리터를 python -m ...으로 호출합니다. Windows에서 로컬 개발 중에는 콘솔 런처를 실행하면 편집 가능한 재설치 중에 pip가 런처를 교체하지 못할 수 있으므로 이 방법을 권장합니다.

Codex

Codex는 사용자 전역 및 프로젝트 로컬 config.toml 파일을 모두 지원합니다.

프로젝트 로컬 Codex 구성

다음을 생성하거나 편집하십시오:

<project>/.codex/config.toml

예를 들어:

[mcp_servers.s2ag]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.s2ag.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

[mcp_servers.s2_recommendations]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.recommendations.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

[mcp_servers.s2_datasets]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.datasets.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

프로젝트 범위의 Codex 구성은 Codex가 신뢰한다고 간주하는 프로젝트에 대해서만 로드됩니다.

사용자 전역 Codex 구성

서버를 Codex에서 프로젝트 전반에 걸쳐 사용할 수 있게 하려면 동일한 구성을 다음 위치에 두십시오:

~/.codex/config.toml

Windows에서는 일반적으로 다음과 같습니다:

%USERPROFILE%\.codex\config.toml

예를 들어:

C:\Users\<username>\.codex\config.toml

MCP 서버 블록 자체는 위의 프로젝트 로컬 예시와 동일합니다.

Codex 구성 확인

터미널에서:

codex mcp list

개별 등록은 다음으로도 확인할 수 있습니다:

codex mcp get s2ag
codex mcp get s2_recommendations
codex mcp get s2_datasets

Claude Code

Claude Code는 프로젝트 공유 MCP 서버와 사용자 범위 MCP 서버를 구분합니다.

프로젝트 로컬 / 프로젝트 공유 Claude 구성

다음을 생성합니다:

<project>/.mcp.json

다음 내용으로:

{
  "mcpServers": {
    "s2ag": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.s2ag.server"
      ]
    },
    "s2_recommendations": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.recommendations.server"
      ]
    },
    "s2_datasets": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.datasets.server"
      ]
    }
  }
}

MCP 구성을 해당 저장소의 다른 사용자와 공유하려는 경우 이 파일을 소비 저장소에 커밋할 수 있습니다.

사용자 전역 Claude 구성

전역 Claude Code 구성의 경우, Claude Code가 사용자 범위 MCP 등록을 관리하도록 하는 것이 선호되는 방법입니다.

다음을 실행하십시오:

claude mcp add --scope user s2ag -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.s2ag.server

claude mcp add --scope user s2_recommendations -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.recommendations.server

claude mcp add --scope user s2_datasets -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.datasets.server

Claude Code는 현재 사용자 범위 MCP 구성을 다음 위치에 저장합니다:

~/.claude.json

Windows에서:

%USERPROFILE%\.claude.json

claude mcp add --scope user를 사용하는 것이 이 파일을 수동으로 편집하는 것보다 선호됩니다. Claude Code가 .claude.json에 추가 상태를 보유하기 때문입니다.

다음으로 등록을 확인하십시오:

claude mcp list

특정 Claude Code 버전에서 사용자 범위 MCP 서버를 로드하는 데 문제가 있는 경우, 프로젝트의 .mcp.json 구성이 가장 간단한 대체 방법입니다.

Semantic Scholar API 키

많은 Semantic Scholar 작업은 인증 없이 작동할 수 있습니다. API 키가 필요한 작업은 다음을 사용합니다:

SEMANTIC_SCHOLAR_API_KEY

키를 MCP 구성 파일에 커밋하지 마십시오.

Windows에서는 사용자 환경 변수로 유지될 수 있습니다:

[Environment]::SetEnvironmentVariable(
    "SEMANTIC_SCHOLAR_API_KEY",
    "YOUR_API_KEY",
    "User"
)

변수를 설정한 후 VS Code, Codex, Claude Code 또는 기타 MCP 호스트를 다시 시작하면 새로 시작되는 MCP 프로세스가 이를 상속받습니다.

MCP 서버는 키가 있으면 자동으로 사용하며, 키가 없으면 Semantic Scholar가 익명 접근을 허용하는 곳에서는 인증되지 않은 상태로 유지됩니다.

프로젝트 로컬 vs. 사용자 전역

유용한 규칙은 다음과 같습니다:

에이전트가 명시적으로 문헌 발견을 수행할 것으로 기대되는 연구 저장소의 경우, 프로젝트 로컬 구성이 일반적으로 더 바람직합니다. 사용 가능한 연구 도구가 저장소와 함께 이동하기 때문입니다.

임의의 프로젝트에서 Semantic Scholar에 일반적으로 개인 접근하려는 경우 사용자 전역 구성이 더 편리합니다.

공유 속도 제한

Semantic Scholar의 초기 인증 속도 제한은 각 MCP 서버에 독립적으로 적용되는 것이 아니라 API 엔드포인트 전반에 걸쳐 적용됩니다.

따라서 이 저장소는 공유 프로세스 간 제한기를 사용합니다:

S2AG MCP ────────────────┐
                         │
Recommendations MCP ─────┼── shared limiter ──> Semantic Scholar
                         │
Datasets MCP ────────────┘

기본 구현은 세 개의 로컬 서버 전체에서 초당 약 1회를 초과하지 않는 업스트림 요청을 허용해야 합니다.

이것은 여러 호스트가 동시에 실행될 때 중요합니다. 예를 들어:

VS Code / Codex
Claude Code
MCP Inspector
tests

제한기는 각 프로세스에서 독립적인 시계를 유지하지 않고 이러한 프로세스들을 조정해야 합니다.

재시도 동작

일시적인 업스트림 실패는 제한된 지수 백오프(bounded exponential backoff)를 사용하여 재시도할 수 있습니다.

예시:

• HTTP 429;

• 일시적인 5xx 응답;

• 임시 네트워크 오류.

Retry-After가 제공되면 이를 존중합니다.

잘못된 요청, 거부된 인증, 누락된 리소스와 같은 일반적인 클라이언트 오류는 반복적으로 재시도되지 않습니다.

재시도는 제한됩니다. MCP는 무한정 재시도하지 않습니다.

S2AG MCP

다음을 실행합니다:

semantic-scholar-s2ag

또는:

python -m semantic_scholar_mcp.s2ag.server

초기 API 표면에는 다음이 포함될 예정입니다:

페이지네이션은 명시적으로 유지됩니다.

인용 요청은 인용 그래프를 재귀적으로 탐색하지 않습니다.

검색은 후속 검색을 자동으로 실행하지 않습니다.

Recommendations MCP

다음을 실행합니다:

semantic-scholar-recommendations

또는:

python -m semantic_scholar_mcp.recommendations.server

초기 표면은 의도적으로 작습니다:

서버는 호출자가 선택한 시드를 Semantic Scholar에 전달합니다.

자체 시드를 선택하거나 결과에 두 번째 LLM 생성 순위를 적용하지 않습니다.

개념적 작업 흐름 예시:

positive:
  paper A
  paper B
  paper C

negative:
  paper D

        │
        ▼

recommend_from_examples

        │
        ▼

Semantic Scholar recommendation ranking

Datasets MCP

다음을 실행합니다:

semantic-scholar-datasets

또는:

python -m semantic_scholar_mcp.datasets.server

초기 도구는 다음과 같습니다:

Datasets MCP는 의도적으로 전체 Semantic Scholar 데이터셋을 자동으로 다운로드하지 않습니다.

일부 Semantic Scholar 데이터셋은 매우 큽니다. 매니페스트를 검색하는 것은 적절한 MCP 작업이지만, 수 기가바이트 규모의 코퍼스 다운로드를 시작하는 것은 명시적인 사용자 제어 도구가 필요합니다.

향후 전용 CLI는 다음과 같은 명령을 제공할 수 있습니다:

s2-dataset download ...
s2-dataset update ...
s2-dataset verify ...

그러한 작업을 암시적 MCP 동작으로 만들지 않고 말입니다.

결정성

이 프로젝트에서 결정적(deterministic)이라는 것은 도구 의미론이 명시적이고 검사 가능함을 의미합니다.

도구는 다음을 수행할 수 있습니다:

validate input
    ↓
wait for rate limiter
    ↓
make one documented API request
    ↓
retry transient transport failures if necessary
    ↓
normalize response
    ↓
return structured data

도구는 조용히 다음이 되어서는 안 됩니다:

search
   ↓
search again with different terms
   ↓
fetch every page
   ↓
walk citations
   ↓
request recommendations
   ↓
rank with an LLM
   ↓
summarize papers

더 높은 수준의 오케스트레이션은 이 저장소의 범위 밖에 있습니다.

페이지네이션

페이지네이션은 호출자가 제어합니다.

Semantic Scholar가 연속 토큰, 오프셋 또는 이에 상응하는 커서를 반환하면 MCP는 해당 값을 반환합니다.

호출자는 명시적으로 다른 페이지를 요청할 수 있습니다.

MCP는 사용 가능한 모든 페이지를 자동으로 가져오지 않습니다.

이는 결정성과 API 사용량을 모두 보호합니다.

필드

Semantic Scholar가 명시적 응답 필드를 지원하는 경우, 도구는 호출자가 필요한 필드만 요청해야 합니다.

사용성을 위해 작은 기본 필드 집합이 제공될 수 있습니다.

초록 또는 인용 컨텍스트와 같은 큰 필드는 문서화된 도구 기본값의 일부가 아닌 한 자동으로 요청되어서는 안 됩니다.

오류

업스트림 조건은 안정적이고 이해 가능한 MCP 오류로 변환되어야 합니다.

예시:

authentication_required
rate_limited
not_found
invalid_request
upstream_error
transport_error

유용한 경우, 구조화된 오류는 다음을 유지할 수 있습니다:

• HTTP 상태;

• 재시도 가능 여부;

• 시도 횟수;

• Semantic Scholar 오류 메시지.

비밀 정보는 절대 포함되어서는 안 됩니다.

개발

단위 테스트 실행:

pytest

린트 실행:

ruff check .

포맷팅 확인:

ruff format --check .

포맷팅 적용:

ruff format .

라이브 Semantic Scholar 테스트는 별도로 표시됩니다:

pytest --run-integration

일반 단위 테스트는 HTTP 상호작용을 모킹해야 하며 Semantic Scholar API 할당량을 소비해서는 안 됩니다.

테스트 철학

가장 중요한 테스트는 API 충실도를 검증합니다.

모든 MCP 도구에 대해 테스트는 다음을 확인해야 합니다:

input
  ↓
exact expected HTTP operation
  ↓
expected response normalization

테스트는 또한 숨은 동작이 없음을 검증해야 합니다.

예를 들어, 단일 인용 요청은 인용 API 작업 하나만 생성해야 하며, 후속 페이지나 참조 문헌을 자동으로 요청해서는 안 됩니다.

연구 도구와의 관계

이 저장소는 도메인 중립적으로 유지되어야 합니다.

예를 들어, 다음을 제공할 수 있습니다:

paper A cites paper B

또는:

Semantic Scholar recommends paper C from seeds A and B

하지만 다음과 같이 결론을 내려서는 안 됩니다:

paper C is the strongest evidence for a particular neuroscience hypothesis

별도의 연구 저장소, Research MCP 또는 인간 연구자가 그러한 해석을 할 수 있습니다.

이러한 분리를 통해 Semantic Scholar 계층은 다음을 유지할 수 있습니다:

• 결정적이며;

• 재사용 가능하며;

• 테스트하기 쉬우며;

• 특정 과학 분야에 독립적이며;

• 다양한 MCP 호스트와 에이전트에서 사용할 수 있습니다.

Semantic Scholar 사용

이 프로젝트는 정당한 연구 목적으로 사용되며 현재 Semantic Scholar API 라이선스와 문서를 준수해야 합니다.

API 사용은 다음을 준수해야 합니다:

• 적용 중인 요청 한도를 존중하며;

• 적절한 경우 일괄/대량 작업을 사용하며;

• 필요한 필드만 요청하며;

• 상한이 있는 지수 백오프를 사용하며;

• API 자격 증명을 보호하며;

• 무제한 API 크롤링을 피하며;

• 진정한 말뭉치 규모의 접근이 필요할 때는 Datasets API를 선호합니다.

Semantic Scholar 응답 데이터를 사용하는 공개 제품이나 표시에는 추가 출처 표시 요구 사항이 있을 수 있습니다. 공개용 데이터 표시를 추가하기 전에 현재 Semantic Scholar 라이선스를 검토하십시오.

이 저장소의 표준 개발 및 API 사용 규칙은 AGENTS.md를 참조하십시오.