Servidor MCP de Unpaywall

Un servidor MCP (Model Context Protocol) que expone herramientas de Unpaywall para que los clientes de IA puedan:

• Obtener metadatos por DOI

• Buscar títulos de artículos

• Recuperar los mejores enlaces a texto completo en acceso abierto (OA)

• Descargar y extraer texto de archivos PDF en acceso abierto

Inicio rápido (npx)

Añade esto a la configuración de tu cliente MCP (ejemplo de Claude Desktop):

{
  "mcpServers": {
    "unpaywall": {
      "command": "npx",
      "args": ["-y", "unpaywall-mcp"],
      "env": { "UNPAYWALL_EMAIL": "you@example.com" }
    }
  }
}

Luego prueba las herramientas: unpaywall_search_titles, unpaywall_get_fulltext_links, unpaywall_fetch_pdf_text.

No necesitas clonar este repositorio ni ejecutar npm install: npx se encarga de la descarga y el almacenamiento en caché en la primera llamada.

Related MCP server: ScholarScope MCP

Requisitos

• Node.js 18+ (para npx)

• Una dirección de correo electrónico para las solicitudes a Unpaywall / OpenAlex (requerido por Unpaywall, utilizado para el grupo de cortesía de OpenAlex).

Desarrollo local (solo para colaboradores)

Los usuarios finales deben usar la configuración de npx anterior. Los colaboradores que compilen desde el código fuente:

npm install
npm run build
UNPAYWALL_EMAIL=you@example.com npm start   # stdio transport, as required by MCP clients

Ejecución en caliente (sin paso de compilación):

UNPAYWALL_EMAIL=you@example.com npm run dev

Herramientas

unpaywall_get_by_doi

• Descripción: Obtener metadatos de Unpaywall para un DOI

• Esquema de entrada:

  • doi (cadena, requerido): ej. 10.1038/nphys1170

  • email (cadena, opcional): sobrescribe UNPAYWALL_EMAIL si se proporciona

• Salida: Respuesta JSON de Unpaywall

unpaywall_search_titles

• Descripción: Buscar títulos de artículos y devolver metadatos OA al estilo de Unpaywall para cada resultado (50 resultados/página)

• Esquema de entrada:

  • query (cadena, requerido): consulta de título

  • is_oa (booleano, opcional): si es verdadero, solo resultados OA; si es falso, solo cerrados; omitir para todos

  • page (entero >= 1, opcional): número de página

  • email (cadena, opcional): sobrescribe UNPAYWALL_EMAIL

• Salida: JSON que coincide con la forma de búsqueda de Unpaywall: results[].response es un registro de estilo DOI (doi, title, is_oa, oa_status, best_oa_location, oa_locations), con score y snippet por resultado. _source: "openalex" marca el origen.

• Nota: Respaldado por el endpoint /works de OpenAlex porque el propio /v2/search de Unpaywall ha estado devolviendo HTTP 500 desde su reescritura en mayo de 2025. Unpaywall ahora funciona como una subrutina de OpenAlex, por lo que este es el equivalente moderno canónico.

unpaywall_get_fulltext_links

• Descripción: Devolver la mejor URL de PDF OA y Open URL para un DOI, además de todas las ubicaciones OA

• Esquema de entrada:

  • doi (cadena, requerido)

  • email (cadena, opcional): sobrescribe UNPAYWALL_EMAIL

• Salida: JSON con campos: best_pdf_url, best_open_url, best_oa_location, oa_locations y metadatos seleccionados

unpaywall_fetch_pdf_text

• Descripción: Descargar y extraer texto del mejor PDF OA para un DOI, o de una pdf_url proporcionada

• Esquema de entrada:

  • pdf_url (cadena, opcional): URL directa del PDF (tiene prioridad)

  • doi (cadena, opcional): utilizado para resolver el mejor PDF OA si no se proporciona pdf_url

  • email (cadena, opcional): requerido si se usa doi y no hay variable de entorno UNPAYWALL_EMAIL

  • truncate_chars (entero >= 1000, opcional): caracteres máximos del texto extraído a devolver (predeterminado 20000)

• Salida: JSON con text (posiblemente truncado), length_chars, truncated, pdf_url y metadatos del PDF

Consejos para prompts de LLM (MCP)

Cuando utilices este servidor desde un cliente LLM habilitado para MCP, pide al modelo que:

• Busque y luego obtenga: Usa unpaywall_search_titles con una frase de título concisa; selecciona un resultado; luego llama a unpaywall_get_fulltext_links o unpaywall_fetch_pdf_text sobre el DOI elegido.

• Prefiera OA: Pasa is_oa: true en las búsquedas cuando solo desees acceso abierto.

• Controle el tamaño: Establece truncate_chars en unpaywall_fetch_pdf_text (predeterminado 20000) y resume textos largos antes de continuar.

• Sea resiliente: Si falta la mejor URL de PDF, recurre a best_open_url y extrae el contenido de la página de destino (fuera de este servidor).

• Respete los límites de tasa: Espacia las solicitudes si realizas muchas llamadas; reutiliza respuestas anteriores en lugar de repetir la misma llamada.

Buenas instrucciones de usuario para el LLM:

• "Encuentra 3 artículos OA sobre 'modelos de base en biomedicina', luego extrae y resume la introducción del mejor."

• "Busca 'Graph Neural Networks survey 2024', filtra por OA si es posible, luego obtén el texto del PDF y produce un resumen de 10 puntos."

Ejemplos de cargas útiles de llamadas a herramientas

Dependiendo de tu cliente MCP, la estructura difiere; las cargas útiles principales son:

// Search titles
{
  "name": "unpaywall_search_titles",
  "arguments": {
    "query": "graph neural networks survey",
    "is_oa": true,
    "page": 1
  }
}

// Get best OA links for a DOI
{
  "name": "unpaywall_get_fulltext_links",
  "arguments": {
    "doi": "10.48550/arXiv.1812.08434"
  }
}

// Fetch and extract PDF text (by DOI)
{
  "name": "unpaywall_fetch_pdf_text",
  "arguments": {
    "doi": "10.48550/arXiv.1812.08434",
    "truncate_chars": 20000
  }
}

Configuración en un cliente MCP

Configuración recomendada (sin compilación) para Claude Desktop usando npm/npx:

{
  "mcpServers": {
    "unpaywall": {
      "command": "npx",
      "args": ["-y", "unpaywall-mcp"],
      "env": {
        "UNPAYWALL_EMAIL": "you@example.com"
      }
    }
  }
}

Configuración alternativa (repositorio local) usando la distribución compilada:

{
  "mcpServers": {
    "unpaywall": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "UNPAYWALL_EMAIL": "you@example.com"
      }
    }
  }
}

Después de añadirlo, pide a tu cliente que liste las herramientas y prueba:

• unpaywall_search_titles con una query

• unpaywall_get_fulltext_links con un doi

• unpaywall_fetch_pdf_text con un doi (o pdf_url)

Notas

• Respeta los límites de tasa y las directrices de uso de Unpaywall: https://unpaywall.org/products/api

• El servidor utiliza transporte stdio y @modelcontextprotocol/sdk.

• Establece UNPAYWALL_EMAIL o pasa email por llamada para que Unpaywall pueda contactarte sobre el uso.

Mantenedores: publicar en npm

# 1) Build the project (also runs automatically on publish)
npm run build

# 2) Bump version (choose patch/minor/major)
npm version patch

# 3) Publish (ensure you are logged in: npm login)
npm publish --access public

# 4) Tag a release on GitHub (optional, recommended)

Los usuarios pueden entonces configurar su cliente MCP con npx -y unpaywall-mcp como se muestra arriba. No se requiere clonar ni compilar.