Scopus MCP Server

Un servidor MCP que envuelve la API de Elsevier Scopus para que un cliente MCP (Claude Desktop, Claude Code o cualquier otro host MCP) pueda buscar y recuperar artículos académicos publicados, algo útil para la verificación de citas y el análisis de estilo de escritura basado en fuentes reales revisadas por pares.

Herramientas

Todas las respuestas son JSON estructurado (consulte Forma de la respuesta más abajo). Cada herramienta devuelve un error estructurado y amigable en lugar de lanzar una excepción cuando la API de Scopus no está disponible, está limitada por tasa o recibe un ID incorrecto; consulte Manejo de errores.

Internamente, el servidor llama a dos APIs de Elsevier:

• Scopus Search API (GET /content/search/scopus) — utilizada por search_scopus.

• Abstract Retrieval API (GET /content/abstract/scopus_id/{id}) — utilizada por get_article_details y get_article_abstract, ya que la Search API no devuelve de forma fiable resúmenes completos, recuentos de citas ni palabras clave.

Related MCP server: MCP-scopus

Estructura del proyecto

mcp-server/
├── src/
│   ├── index.ts          # stdio entry point (for local MCP clients)
│   ├── httpServer.ts      # Streamable HTTP entry point (for remote deployment)
│   ├── registerTools.ts   # tool definitions, shared by both entry points
│   ├── scopusClient.ts    # Elsevier API client: requests, normalization, error mapping
│   ├── types.ts           # TypeScript types for raw Scopus responses + normalized output
│   └── logger.ts          # structured logger → stderr + logs/scopus-mcp.log
├── test/
│   └── test-connection.ts # standalone connectivity test (bypasses the MCP protocol)
├── logs/                  # log file written here at runtime (gitignored)
├── .env.example
├── package.json
└── tsconfig.json

Requisitos previos

• Node.js 18 o posterior (utiliza el fetch global integrado). Compruébelo con node -v.

• Una clave de API de Scopus. Registre una clave gratuita en el Portal para desarrolladores de Elsevier. Tenga en cuenta que Elsevier condiciona el acceso a texto completo/resúmenes según el rango de IP (suscripción institucional) o mediante un Institutional Token; una clave por sí sola es suficiente para probar la conectividad y la búsqueda básica, pero algunos campos pueden estar limitados según sus derechos de acceso.

Configuración

cd mcp-server
npm install
cp .env.example .env

Edite .env y establezca su clave:

SCOPUS_API_KEY=your_real_key_here

SCOPUS_API_KEY se lee de las variables de entorno al iniciar (src/scopusClient.ts); nunca está codificada y .env está en .gitignore, por lo que no puede enviarse por accidente.

Variables de entorno

Pruebe la conectividad primero

Antes de conectar el servidor a cualquier cliente MCP, verifique que la clave de API de Scopus y la ruta de red funcionan:

npm run test:connection

Esto ejecuta test/test-connection.ts, que llama a las mismas funciones de cliente que usan las herramientas, pero directamente, sin hablar el protocolo MCP, con la consulta de ejemplo "farmland abandonment Nepal". Puede pasar su propia consulta en su lugar:

npm run test:connection -- "AUTH(Smith J) AND TITLE(remote sensing)"

Recorre las tres herramientas en secuencia (búsqueda → detalles → resumen del primer resultado) e imprime ✅/❌ en cada paso, además de un registro completo de solicitudes/respuestas en logs/scopus-mcp.log (consulte Registro). El código de salida es 0 solo si todos los pasos se completaron correctamente.

Ejecución local (stdio, para un cliente MCP local)

npm run dev     # runs src/index.ts directly via tsx, no build step
# or
npm run build && npm start   # compiles to dist/ then runs the compiled server

El servidor se comunica a través de stdio, por lo que ejecutarlo directamente en una terminal hará que se quede esperando JSON-RPC en stdin; eso es lo esperado. Está pensado para ser lanzado por un cliente MCP.

Conéctelo a Claude Code

claude mcp add scopus --env SCOPUS_API_KEY=your_real_key_here -- node /absolute/path/to/mcp-server/dist/index.js

(ejecute npm run build primero para que exista dist/index.js), o añádalo al .mcp.json de un proyecto:

{
  "mcpServers": {
    "scopus": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": { "SCOPUS_API_KEY": "your_real_key_here" }
    }
  }
}

Conéctelo a Claude Desktop

Añada el mismo bloque a claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json en Windows, ~/Library/Application Support/Claude/claude_desktop_config.json en macOS) y reinicie Claude Desktop:

{
  "mcpServers": {
    "scopus": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": { "SCOPUS_API_KEY": "your_real_key_here" }
    }
  }
}

Forma de la respuesta

Ejemplo de search_scopus (truncado):

{
  "query": "farmland abandonment Nepal",
  "totalResults": 42,
  "returnedResults": 10,
  "articles": [
    {
      "scopusId": "85123456789",
      "eid": "2-s2.0-85123456789",
      "title": "Drivers of farmland abandonment in the mid-hills of Nepal",
      "authors": ["Sharma B.", "Poudel K."],
      "publicationYear": 2021,
      "sourceTitle": "Land Use Policy",
      "doi": "10.1016/j.landusepol.2021.105123",
      "doiUrl": "https://doi.org/10.1016/j.landusepol.2021.105123",
      "scopusUrl": "https://www.scopus.com/inward/record.uri?...",
      "citedByCount": 17,
      "abstract": null,
      "documentType": "Article"
    }
  ]
}

get_article_details añade keywords, subjectAreas, openAccess y aggregationType además de los mismos campos. get_article_abstract devuelve { scopusId, title, abstract, hasAbstract }.

Los campos que Scopus no tiene para un registro concreto se devuelven como null (o [] para campos de lista, o hasAbstract: false) en lugar de omitirse; compruebe si hay null/false antes de suponer que falta un campo debido a un error.

Manejo de errores

Cada herramienta captura los errores internamente y devuelve isError: true con un cuerpo JSON estructurado en lugar de hacer fallar la conexión MCP:

{
  "error": true,
  "kind": "rate_limited",
  "message": "Scopus API rate limit exceeded (HTTP 429) for search_scopus(...). Retry after 30s.",
  "status": 429,
  "retryAfterSeconds": 30
}

kind es uno de: unauthorized (clave de API incorrecta o ausente), rate_limited (HTTP 429), not_found (ID de Scopus incorrecto / HTTP 404), bad_request (consulta vacía, entrada con formato incorrecto), network_error (fallo de DNS/conexión), timeout (se excedió SCOPUS_REQUEST_TIMEOUT_MS) o unknown. Una búsqueda que tiene éxito pero no encuentra coincidencias no es un error: devuelve totalResults: 0 y un message legible que sugiere cómo ampliar la consulta.

Registro

Todas las llamadas y respuestas de la API se registran para depuración:

• Cada solicitud registra su URL (con la clave de API oculta) antes de enviarse.

• Cada respuesta registra el código de estado, el tiempo transcurrido y una vista previa de 500 caracteres del cuerpo.

• Los registros van a stderr como JSON de una sola línea (nunca a stdout; stdout está reservado para el protocolo MCP en el transporte stdio) y también se añaden a logs/scopus-mcp.log.

• Establezca LOG_LEVEL=debug para más detalle, o LOG_LEVEL=error para reducir el ruido.

Despliegue en una plataforma remota/sin servidor (Render, Railway, etc.)

El transporte stdio (src/index.ts) solo funciona con clientes MCP que puedan ejecutar un proceso local; no es accesible a través de la red. Para alojar este servidor de forma remota, use el punto de entrada Streamable HTTP en su lugar: src/httpServer.ts. Sirve las mismas tres herramientas en POST /mcp y añade un endpoint GET /healthz para las comprobaciones de estado de la plataforma.

Ni Render ni Railway son realmente "sin servidor" (no hay arranques en frío de escala a cero a mitad de solicitud): ambos ejecutan esto como un proceso Node persistente normal, que es lo que necesita un protocolo con estado como MCP. Considere "plataforma sin servidor" aquí como "alojamiento Node gestionado".

Render

1. Suba este repositorio (o solo la carpeta mcp-server/) a GitHub.

2. En el panel de Render: Nuevo → Web Service, conecte el repositorio, establezca directorio raíz en mcp-server si es una subcarpeta de un repositorio más grande.

3. Comando de compilación: npm install && npm run build

4. Comando de inicio: npm run start:http

5. En Entorno, añada:

   • SCOPUS_API_KEY = su clave (márquela como secreta)

   • MCP_HTTP_AUTH_TOKEN = una cadena aleatoria larga que usted genere (p. ej. openssl rand -hex 32)

   • opcionalmente MCP_ALLOWED_HOSTS = el nombre de host de su instancia de Render, p. ej. scopus-mcp.onrender.com

6. Render establece PORT automáticamente; httpServer.ts lo lee, no se necesita ninguna acción.

7. Despliegue. Ruta de comprobación de estado: /healthz.

Railway

1. Nuevo proyecto → Desplegar desde repositorio de GitHub, establezca la raíz del servicio en mcp-server si es necesario.

2. Railway detecta Node automáticamente; si no ejecuta el comando correcto, establezca:

   • Comando de compilación: npm install && npm run build

   • Comando de inicio: npm run start:http

3. En Variables, añada SCOPUS_API_KEY y MCP_HTTP_AUTH_TOKEN como arriba.

4. Railway inyecta PORT automáticamente.

5. Una vez desplegado, su endpoint MCP es https://<your-app>.up.railway.app/mcp.

Conexión de un cliente MCP al servidor alojado

claude mcp add --transport http scopus https://<your-app>/mcp \
  --header "Authorization: Bearer <your MCP_HTTP_AUTH_TOKEN>"

Notas de seguridad para el despliegue HTTP

• Establezca siempre MCP_HTTP_AUTH_TOKEN. Sin él, cualquiera que tenga la URL puede llamar a sus herramientas y consumir su cuota de API de Scopus; el servidor registra una advertencia al inicio si no está definido.

• El servidor activa automáticamente la protección contra la re-vinculación de DNS para localhost/127.0.0.1; para un despliegue real con 0.0.0.0, establezca MCP_ALLOWED_HOSTS al nombre de host de su plataforma.

• Rote SCOPUS_API_KEY y MCP_HTTP_AUTH_TOKEN mediante el administrador de secretos de su plataforma, nunca confirmándolos en el repositorio.

• Considere poner el límite de tasa de la propia plataforma o un proxy inverso delante para despliegues públicos, además de los límites de tasa por clave de Elsevier.

Solución de problemas

Licencia

MIT