SemanticScholar_MCP

Interfaces deterministas del Model Context Protocol para las tres familias de API de Semantic Scholar:

• S2AG — búsqueda en Academic Graph, metadatos, autores, citas y referencias.

• Recommendations — el servicio de recomendación de artículos de Semantic Scholar.

• Datasets — descubrimiento de versiones, manifiestos de conjuntos de datos y actualizaciones incrementales de conjuntos de datos.

El proyecto proporciona deliberadamente envoltorios finos de API en lugar de un sistema agéntico de investigación bibliográfica.

Diseño

La regla central es:

Una invocación de herramienta MCP representa una operación documentada de Semantic Scholar.

Los servidores realizan tareas a nivel de transporte, como validación, autenticación, limitación de velocidad, reintentos y normalización de respuestas.

No deciden qué literatura es científicamente importante.

Por ejemplo:

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

La expansión de búsqueda, la interpretación científica, el resumen, la estrategia de exploración del grafo de citas y la síntesis de investigación siguen siendo responsabilidad del agente consumidor.

Related MCP server: Semantic Scholar MCP Server

Estructura del repositorio

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

Requisitos

• Python 3.11 o superior

• Acceso a Semantic Scholar a través de Internet

• Clave de API de Semantic Scholar opcional

La implementación usa la línea v2 actual del SDK oficial de Python para MCP.

Instalación

Cree un entorno virtual:

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

Instale el paquete en modo editable con las dependencias de desarrollo:

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

Alternativamente, con uv:

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

Python 3.14 no es necesario; el proyecto es compatible con Python 3.11 y versiones posteriores.

Después de configurar el entorno del paquete Python, ejecute opcionalmente las pruebas:

pytest
ruff check .
ruff format --check .

Si ya ha configurado SEMANTIC_SCHOLAR_API_KEY como variable de entorno del sistema (consulte la siguiente sección, Autenticación), también puede probar la integración en vivo:

pytest --run-integration

Nota: Si establece la variable de entorno del sistema con su clave de API después de iniciar cualquier ventana de VSCode, debe cerrar todas las ventanas de VSCode para reiniciar VSCode por completo antes de que el entorno del sistema sea capturado por las herramientas ejecutadas a través de las extensiones de VSCode.

Autenticación

Semantic Scholar permite el acceso sin autenticación a muchas operaciones de la API.

Cuando haya una clave de API disponible, expóngala a los procesos MCP mediante:

$env:SEMANTIC_SCHOLAR_API_KEY = "..."

No coloque la clave en:

• .mcp.json;

• .codex/config.toml;

• código fuente;

• archivos .env confirmados;

• archivos de prueba.

Los servidores MCP usan la clave automáticamente cuando está presente.

Las operaciones que requieren autenticación deberían devolver un error explícito cuando no hay ninguna clave configurada.

Nota (de nuevo): Si establece la variable de entorno del sistema con su clave de API después de iniciar cualquier ventana de VSCode, debe cerrar todas las ventanas de VSCode para reiniciar VSCode por completo antes de que el entorno del sistema sea capturado por las herramientas ejecutadas a través de las extensiones de VSCode.

Actualizaciones de compilación

Los scripts .\rebuild.ps1 y .\version.ps1 se proporcionan como utilidades para facilitar las actualizaciones de versión al recompilar:

rebuild.ps1

Para recompilar sin incrementar automáticamente el número de patch, especifique explícitamente la opción:

.\rebuild.ps1 -SkipVersionIncrement

De lo contrario, .\rebuild.ps1 incrementa automáticamente el número de patch directamente en pyproject.toml.

version.ps1

Para incrementar <major> | <minor> | <patch> sin recompilar:

.\version.ps1 patch -NoRebuild

Para incrementar la versión minor, restableciendo patch a 0, y recompilar:

.\version.ps1 minor

Para incrementar la versión major, restableciendo tanto minor como patch a 0, y recompilar:

.\version.ps1 major

Configuración del cliente MCP

Los tres servidores MCP de Semantic Scholar pueden configurarse:

• a nivel de proyecto, de modo que estén disponibles solo dentro de un repositorio concreto; o

• a nivel de usuario, de modo que estén disponibles en todos los repositorios.

Los servidores son:

• s2ag — Semantic Scholar Academic Graph

• s2_recommendations — Semantic Scholar Recommendations API

• s2_datasets — Semantic Scholar Datasets API

Los ejemplos siguientes asumen que este repositorio está instalado en:

C:\MyRepos\Python\SemanticScholar_MCP

Ajuste la ruta según sea necesario.

Los ejemplos invocan deliberadamente el intérprete de Python del entorno virtual con python -m ... en lugar de invocar directamente los lanzadores de consola semantic-scholar-*.exe generados. Esto se recomienda durante el desarrollo local en Windows porque ejecutar los lanzadores de consola puede impedir que pip los reemplace durante una reinstalación editable.

Codex

Codex admite tanto archivos config.toml globales de usuario como locales de proyecto.

Configuración de Codex local de proyecto

Cree o edite:

<project>/.codex/config.toml

Por ejemplo:

[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

La configuración de Codex con ámbito de proyecto se carga solo para proyectos que Codex considera de confianza.

Configuración de Codex global de usuario

Para que los servidores estén disponibles para Codex en todos los proyectos, coloque la misma configuración en:

~/.codex/config.toml

En Windows normalmente es:

%USERPROFILE%\.codex\config.toml

Por ejemplo:

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

Los bloques de servidor MCP en sí son idénticos al ejemplo local de proyecto anterior.

Verificar la configuración de Codex

Desde una terminal:

codex mcp list

Los registros individuales también pueden inspeccionarse con:

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

Claude Code

Claude Code distingue entre servidores MCP compartidos de proyecto y servidores MCP con ámbito de usuario.

Configuración de Claude local de proyecto / compartida de proyecto

Cree:

<project>/.mcp.json

con:

{
  "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"
      ]
    }
  }
}

Este archivo puede confirmarse en el repositorio consumidor cuando se pretenda compartir la configuración de MCP con otros usuarios de ese repositorio.

Configuración de Claude global de usuario

Para la configuración global de Claude Code, el enfoque preferido es permitir que Claude Code gestione los registros MCP con ámbito de usuario.

Ejecute:

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 almacena actualmente la configuración MCP con ámbito de usuario en:

~/.claude.json

En Windows:

%USERPROFILE%\.claude.json

Usar claude mcp add --scope user es preferible a editar este archivo manualmente porque Claude Code posee estado adicional en .claude.json.

Verifique los registros con:

claude mcp list

Si una versión concreta de Claude Code tiene problemas para cargar servidores MCP con ámbito de usuario, la configuración .mcp.json del proyecto es el recurso alternativo más sencillo.

Clave de API de Semantic Scholar

Muchas operaciones de Semantic Scholar pueden funcionar sin autenticación. Las operaciones que requieren una clave de API usan:

SEMANTIC_SCHOLAR_API_KEY

No confirme la clave en un archivo de configuración de MCP.

En Windows, puede persistirse como variable de entorno de usuario:

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

Reinicie VS Code, Codex, Claude Code u otros hosts MCP después de establecer la variable para que los procesos MCP recién iniciados la hereden.

Los servidores MCP usan la clave automáticamente cuando está presente y, en caso contrario, permanecen sin autenticación donde Semantic Scholar permite el acceso anónimo.

Local de proyecto vs. global de usuario

Una regla útil es:

Para un repositorio de investigación cuyos agentes deben realizar explícitamente descubrimiento bibliográfico, la configuración local de proyecto suele ser preferible porque las herramientas de investigación disponibles viajan con el repositorio.

Para el acceso personal general a Semantic Scholar desde proyectos arbitrarios, la configuración global de usuario es más conveniente.

Limitación de velocidad compartida

El límite de velocidad autenticado inicial de Semantic Scholar se aplica a todos los endpoints de la API, no de forma independiente a cada servidor MCP.

Por lo tanto, este repositorio utiliza un limitador interproceso compartido:

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

La implementación predeterminada debería permitir no más de aproximadamente una solicitud al servicio ascendente por segundo en los tres servidores locales.

Esto es importante cuando varios hosts se ejecutan simultáneamente, por ejemplo:

VS Code / Codex
Claude Code
MCP Inspector
tests

El limitador debería coordinar estos procesos en lugar de mantener un reloj independiente en cada uno.

Comportamiento de reintentos

Los fallos transitorios del servicio ascendente pueden reintentarse mediante un retroceso exponencial acotado.

Los ejemplos incluyen:

• HTTP 429;

• respuestas 5xx transitorias;

• fallos de red temporales.

Se respeta Retry-After cuando se proporciona.

Los errores comunes de cliente, como solicitudes no válidas, autenticación rechazada y recursos inexistentes, no se reintentan repetidamente.

Los reintentos están acotados; el MCP nunca reintenta indefinidamente.

S2AG MCP

Ejecute:

semantic-scholar-s2ag

o:

python -m semantic_scholar_mcp.s2ag.server

La superficie inicial de la API pretende incluir:

La paginación sigue siendo explícita.

Una solicitud de citas no recorre recursivamente el grafo de citas.

Una búsqueda no emite automáticamente búsquedas de seguimiento.

Recommendations MCP

Ejecute:

semantic-scholar-recommendations

o:

python -m semantic_scholar_mcp.recommendations.server

La superficie inicial es deliberadamente pequeña:

El servidor pasa a Semantic Scholar las semillas seleccionadas por el llamante.

No elige sus propias semillas ni aplica una segunda clasificación generada por LLM a los resultados.

Flujo de trabajo conceptual de ejemplo:

positive:
  paper A
  paper B
  paper C

negative:
  paper D

        │
        ▼

recommend_from_examples

        │
        ▼

Semantic Scholar recommendation ranking

Datasets MCP

Ejecute:

semantic-scholar-datasets

o:

python -m semantic_scholar_mcp.datasets.server

Las herramientas iniciales son:

El MCP de Datasets deliberadamente no descarga automáticamente conjuntos de datos completos de Semantic Scholar.

Algunos conjuntos de datos de Semantic Scholar son muy grandes. Recuperar un manifiesto es una operación MCP apropiada; iniciar la descarga de un corpus de varios gigabytes requiere herramientas explícitas controladas por el usuario.

Una CLI dedicada futura podría proporcionar comandos como:

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

sin convertir esas operaciones en comportamiento implícito del MCP.

Determinismo

Para este proyecto, determinista significa que la semántica de las herramientas es explícita e inspeccionable.

Una herramienta puede:

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

Una herramienta no debe convertirse silenciosamente en:

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

La orquestación de nivel superior queda fuera de este repositorio.

Paginación

La paginación está controlada por el llamante.

Cuando Semantic Scholar devuelve un token de continuación, un desplazamiento o un cursor equivalente, el MCP devuelve ese valor.

El llamante puede solicitar explícitamente otra página.

El MCP no obtiene automáticamente todas las páginas disponibles.

Esto protege tanto el determinismo como el uso de la API.

Campos

Cuando Semantic Scholar admite campos de respuesta explícitos, las herramientas deberían solicitar solo los campos que necesita el llamante.

Se puede proporcionar un pequeño conjunto de campos predeterminado para facilitar su uso.

Los campos grandes, como los resúmenes o los contextos de citas, no deberían solicitarse automáticamente a menos que formen parte del valor predeterminado documentado de la herramienta.

Errores

Las condiciones del servicio ascendente deberían traducirse en errores MCP estables y comprensibles.

Ejemplos:

authentication_required
rate_limited
not_found
invalid_request
upstream_error
transport_error

Cuando sea útil, el error estructurado puede conservar:

• estado HTTP;

• capacidad de reintento;

• número de intentos;

• mensaje de error de Semantic Scholar.

Los secretos nunca deben incluirse.

Desarrollo

Ejecutar pruebas unitarias:

pytest

Ejecutar linting:

ruff check .

Comprobar el formato:

ruff format --check .

Aplicar el formato:

ruff format .

Las pruebas en vivo de Semantic Scholar se marcan por separado:

pytest --run-integration

Las pruebas unitarias ordinarias deben simular las interacciones HTTP y no deben consumir la cuota de la API de Semantic Scholar.

Filosofía de pruebas

Las pruebas más importantes verifican la fidelidad de la API.

Para cada herramienta de MCP, las pruebas deben confirmar:

input
  ↓
exact expected HTTP operation
  ↓
expected response normalization

Las pruebas también deben verificar la ausencia de comportamiento oculto.

Por ejemplo, una única solicitud de cita debe generar una operación de la API de citas, no solicitar automáticamente páginas o referencias posteriores.

Relación con las herramientas de investigación

Este repositorio debe permanecer neutral en cuanto al dominio.

Por ejemplo, puede exponer:

paper A cites paper B

o:

Semantic Scholar recommends paper C from seeds A and B

pero no debe concluir:

paper C is the strongest evidence for a particular neuroscience hypothesis

Un repositorio de investigación separado, Research MCP o un investigador humano puede hacer esa interpretación.

Esta separación permite que la capa de Semantic Scholar siga siendo:

• determinista;

• reutilizable;

• fácil de probar;

• independiente de cualquier campo científico específico;

• utilizable por diferentes hosts y agentes de MCP.

Uso de Semantic Scholar

Este proyecto está destinado a un uso legítimo de investigación y debe cumplir con la licencia y la documentación actuales de la API de Semantic Scholar.

El uso de la API debe:

• respetar los límites de tasa activos;

• usar operaciones por lotes/masivas cuando corresponda;

• solicitar solo los campos necesarios;

• utilizar retroceso exponencial acotado;

• proteger las credenciales de la API;

• evitar el rastreo no restringido de la API;

• preferir la API de Datasets cuando se requiera acceso realmente a escala de corpus.

Los productos o visualizaciones públicos que utilicen datos de respuesta de Semantic Scholar pueden tener requisitos adicionales de atribución. Revise la licencia actual de Semantic Scholar antes de añadir una presentación de datos dirigida al público.

Consulte AGENTS.md para conocer las reglas normativas de desarrollo y uso de la API de este repositorio.