openalex-mcp-server

---

Herramientas

Cinco herramientas para consultar el catálogo de investigación académica de OpenAlex:

Nombre de la herramienta	Descripción
openalex_search_entities	Buscar, filtrar, ordenar o recuperar por ID en los 8 tipos de entidades.
openalex_analyze_trends	Agregación por grupos para análisis de tendencias y distribución.
openalex_resolve_name	Resolver un nombre o un identificador (DOI, ORCID, ROR, PMID, PMCID, ISSN, ID de OpenAlex) a un ID de OpenAlex.
openalex_get_citation_graph	Recorrer el grafo de citas un salto desde una obra semilla: cita, citado_por o relacionado_con.
openalex_describe_fields	Listar nombres de campos válidos para filtros, agrupaciones y selecciones de un tipo de entidad: llámalo antes de construir una consulta para evitar errores de campo no válido.

openalex_search_entities

Herramienta principal de descubrimiento y consulta. Cubre todos los tipos de entidades de OpenAlex (obras, autores, fuentes, instituciones, temas, palabras clave, editoriales, financiadores).

• Recuperar una sola entidad por ID (ID de OpenAlex, DOI, ORCID, ROR, PMID, PMCID, ISSN). id tiene prioridad: los criterios de búsqueda pasados junto con él no se aplican, y la respuesta indica cuáles se descartaron en lugar de devolverlos como si se hubieran ejecutado. Las validaciones solo de búsqueda (límite semántico de página, sample con cursor, seed sin sample) también se omiten: una consulta por ID nunca se rechaza por parámetros que ignora.
• Búsqueda por palabras clave con operadores booleanos, frases entre comillas, comodines y coincidencia difusa.
• Modos de búsqueda semántica exacta y con IA.
• Sintaxis de filtros enriquecida: AND entre campos, OR dentro de campos (us|gb), NOT (!us), rangos (2020-2024), comparaciones (>100).
• Selección de campos predeterminada sensata por tipo de entidad, aplicada tanto a búsquedas como a consultas por ID: evita respuestas demasiado grandes; pasa select para elegir campos, o ["*"] para el registro completo.
• Los nombres de campo no válidos en select producen un error que lista los campos válidos para ese tipo de entidad.
• La salida MCP formateada es un renderizador de Markdown genérico: cada campo devuelto se muestra sin codificación fija por tipo de entidad.
• Paginación por cursor y hasta 100 resultados por página; sort acepta una sola clave o una lista separada por comas, con el prefijo descendente - aplicado por clave.
• display_name es anulable: OpenAlex no tiene título para paratextos y otros registros sin título, que pasan en lugar de fallar en toda la página.

---

openalex_analyze_trends

Agregar entidades en grupos y contarlas para análisis de tendencias, distribución y comparativas.

• Agrupar por cualquier campo admitido (año de publicación, estado de acceso abierto, institución, país, tema, etc.).
• Combinar con filtros para delimitar la población antes de la agregación.
• Hasta 200 grupos por página con paginación por cursor.
• Admite include_unknown para mostrar entidades sin valor en el campo agrupado.

---

openalex_resolve_name

La puerta de entrada para convertir cualquier cosa que tengas en un ID de OpenAlex. Úsalo siempre antes de filtrar por entidad: los nombres son ambiguos, los IDs no.

• Un nombre o nombre parcial ejecuta una búsqueda de autocompletado: hasta 10 coincidencias con pistas de desambiguación, ~200 ms.
• Un identificador se resuelve de forma determinista al único registro al que apunta: ID de OpenAlex, DOI, ORCID, ROR, PMID, PMCID o ISSN, desnudo o en forma de URL. No se necesita entity_type: el identificador determina su propio tipo.
• Un identificador que no coincide con nada devuelve un resultado vacío que nombra el esquema, no consejos de búsqueda por nombre.
• Filtro opcional por tipo de entidad y filtros a nivel de campo, aplicados a consultas por nombre.

---

openalex_get_citation_graph

Recorrido de un salto en el grafo de citas desde una obra semilla. Envuelve los filtros cites/cited_by/related_to de OpenAlex detrás de un argumento explícito direction para que los llamadores no tengan que conocer los nombres de los filtros.

• cites: obras que citan la semilla (citas entrantes).
• cited_by: obras que la semilla cita (su lista de referencias).
• related_to: "obras relacionadas" algorítmicas de OpenAlex (~8-30 típicas, puede estar vacío para semillas poco citadas).
• Acepta IDs de OpenAlex, DOIs, PMIDs, PMCIDs como seed_id; valida la semilla mediante una consulta singleton /works/{id} antes de recorrer, por lo que las semillas inexistentes aparecen como NotFound.
• Se combina con filters/sort/select para acotar el grafo (p. ej., publication_year=">2020", is_oa="true").

---

openalex_describe_fields

Descubre nombres de campo válidos antes de construir una consulta: evita errores 400 de campo no válido. Respaldado por un catálogo generado a partir de la propia validación de campos de OpenAlex.

• Lista campos válidos para cualquier tipo de entidad y contexto (filter, group_by o select).
• group_by devuelve el subconjunto del conjunto filter que OpenAlex puede agregar: los campos de fecha sin procesar, los operadores *.search y los modificadores de rango from_*/to_* quedan excluidos.
• Pasa query (un nombre parcial o adivinado) para ordenar los resultados por similitud de nombre: aparece el campo correcto cuando solo sabes aproximadamente lo que quieres.
• Complementa las sugerencias clasificadas "quisiste decir" que ahora se añaden a los errores de campo no válido en las herramientas de búsqueda, tendencias y grafo de citas.

Prompts

Prompt	Descripción
openalex_literature_review	Guía una búsqueda bibliográfica sistemática: formula la consulta, busca, filtra, analiza la red de citas, sintetiza los hallazgos.
openalex_research_landscape	Analiza el panorama de investigación de un tema: tendencias de volumen, principales autores/instituciones, tasas de acceso abierto, fuentes de financiación.

Características

Construido sobre @cyanheads/mcp-ts-core:

• Definiciones declarativas de herramientas: un archivo por herramienta, el framework gestiona el registro y la validación.
• Manejo unificado de errores en todas las herramientas.
• Autenticación conectable (none, jwt, oauth).
• Backends de almacenamiento intercambiables mediante el framework (no utilizados actualmente por este servidor).
• Registro estructurado con trazado OpenTelemetry opcional.
• Se ejecuta localmente (stdio/HTTP) o en Docker desde el mismo código base.

Específico de OpenAlex:

• Cliente API tipado con normalización automática de IDs (DOI, ORCID, ROR, PMID, PMCID, ISSN, URLs de OpenAlex).
• Reconstrucción de resúmenes a partir de índices invertidos: texto plano en lugar de la codificación posicional de OpenAlex.
• Los códigos de estado HTTP se asignan a clases de error MCP específicas (400 → InvalidParams, 422 → ValidationError, 429 → RateLimited, etc.) con los mensajes ascendentes mostrados.
• Cada herramienta que llama a la API informa cuánto gastó la llamada del presupuesto diario de OpenAlex y cuánto queda, para que un barrido paginado pueda calcularse antes de ejecutarse en lugar de terminar en un 429. Una cuenta con saldo prepagado también lo ve, ya que sigue sirviendo una vez agotada la asignación del día.
• Reintentos de solicitud sensibles al tiempo de espera y soporte de cancelación mediante AbortSignal.

Primeros pasos

Instancia pública alojada

Hay una instancia pública disponible en https://openalex.caseyjhand.com/mcp: no requiere instalación. Apunta cualquier cliente MCP a ella mediante Streamable HTTP:

{
  "mcpServers": {
    "openalex-mcp-server": {
      "type": "streamable-http",
      "url": "https://openalex.caseyjhand.com/mcp"
    }
  }
}

Autohospedado / Local

Añádelo a la configuración de tu cliente MCP (p. ej., claude_desktop_config.json):

{
  "mcpServers": {
    "openalex-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/openalex-mcp-server"],
      "env": {
        "OPENALEX_API_KEY": "your-openalex-api-key"
      }
    }
  }
}

OPENALEX_API_KEY es opcional: configúralo con una clave de cuenta gratuita de OpenAlex para límites de velocidad con clave y presupuesto bajo el precio basado en uso de OpenAlex, u omítelo para acceso anónimo. Configura OPENALEX_MAILTO con un correo electrónico si quieres identificarte ante OpenAlex (el grupo de cortesía).

Requisitos previos

• Bun v1.3.0 o superior (para desarrollo)

Instalación

1. Clona el repositorio:

git clone https://github.com/cyanheads/openalex-mcp-server.git

2. Navega al directorio:

cd openalex-mcp-server

3. Instala las dependencias:

bun install

Configuración

Variable	Descripción	Predeterminado
OPENALEX_API_KEY	Opcional. Clave API de cuenta de OpenAlex, enviada ascendente como api_key= (gratuita en openalex.org/settings/api). Sin ella, se aplican límites de velocidad anónimos.	—
OPENALEX_MAILTO	Opcional. Correo electrónico enviado ascendente como mailto= para identificarte ante OpenAlex (el grupo de cortesía). Un identificador de cortesía, separado de la clave API.	—
OPENALEX_BASE_URL	URL base de la API de OpenAlex.	https://api.openalex.org
MCP_TRANSPORT_TYPE	Transporte: stdio o http.	stdio
MCP_HTTP_PORT	Puerto para el servidor HTTP.	3010
MCP_AUTH_MODE	Modo de autenticación: none, jwt o oauth.	none
MCP_ALLOWED_ORIGINS	Lista de permitidos separada por comas de cabeceras Origin del navegador para transporte HTTP. Sin configurar = solo bucle local; configúralo en * para desactivarlo.	solo bucle local
MCP_LOG_LEVEL	Nivel de registro (RFC 5424).	debug
LOGS_DIR	Directorio para archivos de registro (solo Node.js).	<project-root>/logs
OTEL_ENABLED	Habilitar instrumentación OpenTelemetry (tramos, métricas, registros de finalización).	false

Ejecutar el servidor

Desarrollo local

• Compila y ejecuta la versión de producción:

  bun run build
  bun run start:http   # or start:stdio
  

• Ejecuta comprobaciones y pruebas:

  bun run devcheck     # Lints, formats, type-checks
  bun run test         # Runs test suite
  

Docker

docker build -t openalex-mcp-server .
docker run -e OPENALEX_API_KEY=your-key -p 3010:3010 openalex-mcp-server

Estructura del proyecto

Directorio	Propósito
src/mcp-server/tools/definitions/	Definiciones de herramientas (*.tool.ts).
src/mcp-server/prompts/definitions/	Definiciones de prompts (*.prompt.ts).
src/services/openalex/	Servicio de cliente API de OpenAlex y tipos de dominio.
src/config/	Análisis y validación de variables de entorno con Zod.
tests/	Pruebas unitarias y de integración, que reflejan la estructura de src/.

Guía de desarrollo

Consulta CLAUDE.md para las pautas de desarrollo y reglas arquitectónicas. La versión corta:

• Los manejadores lanzan, el framework captura: sin try/catch en la lógica de herramientas.
• Usa ctx.log para el registro, ctx.state para el almacenamiento.
• Siempre resuelve nombres a IDs mediante openalex_resolve_name antes de usarlos en filtros.

Contribuciones

Se aceptan problemas y solicitudes de extracción. Ejecuta las comprobaciones antes de enviar:

bun run devcheck
bun run test

Licencia

Apache-2.0: consulta LICENSE para más detalles.