arxiv-mcp-server

---

Resumen

Artículos de arXiv, metadatos y texto completo desde la API de arXiv y su fuente de metadatos OAI-PMH. Busca artículos por consulta, categoría y fecha de envío; obtén metadatos estructurados por ID; y lee el texto completo del artículo con respaldo automático entre renders HTML y PDF. Se ejecuta como proceso stdio, como servidor local Streamable HTTP, o mediante el endpoint público alojado de arriba.

Herramientas

Herramienta	Descripción
arxiv_search	Busca artículos de arXiv por consulta con prefijos de campo, categoría y filtros de fecha
arxiv_get_metadata	Obtén metadatos de uno o más artículos por ID de arXiv
arxiv_read_paper	Lee el texto completo del artículo vía HTML, ar5iv o respaldo extraído de PDF
arxiv_list_categories	Lista la taxonomía de categorías de arXiv, opcionalmente filtrada por grupo

Recursos

Recurso	Descripción
arxiv://paper/{paperId}	Metadatos del artículo por ID de arXiv
arxiv://categories	Taxonomía completa de categorías de arXiv

Referencia de capacidades

arxiv_search _herramienta

• Prefijos de campo ti:, au:, abs:, cat:, co: (comentario), jr: (referencia de revista), all: (todos los campos); booleanos AND / OR / ANDNOT; consulta limitada a 1000 caracteres
• category acepta un código hoja (cs.CL) o un archivo completo (astro-ph, cs, math) — un archivo simple coincide con sus clases de materia más los artículos heredados anteriores a la subdivisión
• sort_by (relevance / submitted / updated) y sort_order (ascending / descending); hasta 50 resultados por llamada (max_results)
• submitted_from / submitted_to acotan la fecha de envío de forma inclusiva (UTC YYYY-MM-DD); las ventanas consecutivas cubren coincidencias sin huecos — deduplica por ID en la unión — la forma de alcanzar resultados más allá del límite de paginación de 10,000 start
• El enriquecimiento de la respuesta refleja la consulta efectiva (cada filtro incorporado, reproducible), el recuento total de coincidencias y el desplazamiento de página; las páginas vacías o sobregiradas llevan orientación de recuperación en lugar de un error

---

arxiv_get_metadata _herramienta

• Hasta 10 IDs por llamada (cadena única o arreglo); formatos versionados (2401.12345v2), sin versión y heredados (hep-th/9901001) aceptados
• Resultados parciales por lote: artículos encontrados más un not_found[] tipado (not_in_arxiv / version_not_in_mirror) para el resto — nunca falla todo el lote por un ID incorrecto
• Falla no_match solo cuando todos los IDs fallan; falla version_unavailable cuando cada fallo es una brecha de versión solo-espejo alcanzable en la API en vivo

---

arxiv_read_paper _herramienta

• Prueba primero el HTML nativo de arXiv, luego ar5iv, luego el texto extraído del PDF — el campo source informa cuál respondió
• Elimina el encabezado/plantilla HTML y colapsa MathML a LaTeX delimitado por signos de dólar ($…$ en línea, $$…$$ en bloque) para que el presupuesto de caracteres se centre en el contenido del artículo
• Devuelve HTML crudo para fuentes HTML — el LLM interpreta el contenido directamente; los cuerpos extraídos de PDF son texto plano, por lo que la prosa es confiable pero las matemáticas, tablas y estructura de encabezados se aplanan
• max_characters por defecto es 100,000; pasa null para el artículo completo en una sola llamada. El HTML crudo puede ocupar 500KB-3MB+ para artículos con muchas matemáticas — pagina con start en su lugar
• Fallos tipados: content_unavailable (sin render, sin PDF), pdf_extraction_failed (el PDF no tiene capa de texto), version_unavailable (ID con versión fijada necesita la API en vivo)

---

arxiv_list_categories _herramienta

• ~155 categorías en 8 grupos de nivel superior (cs, econ, eess, math, physics, q-bio, q-fin, stat)
• Filtro opcional group para reducir resultados
• Datos estáticos — siempre tiene éxito

---

arxiv://paper/{paperId} _recurso

• paperId acepta formatos versionados, sin versión y heredados — misma resolución que arxiv_get_metadata
• Codifica en porcentaje la barra de un ID heredado: arxiv://paper/hep-th%2F9901001
• Errores tipados: empty_id, no_match, version_unavailable

---

arxiv://categories _recurso

• Taxonomía completa de categorías de arXiv como { categories: [...] }, un arreglo plano con code / name / group por entrada
• Cacheable por 24h (cacheHint.ttlMs: 86400000), ámbito público
• Sin parámetros

Características

Construido sobre @cyanheads/mcp-ts-core: transportes stdio y Streamable HTTP, autenticación conectable (none / jwt / oauth), almacenamiento intercambiable (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), registro estructurado con trazado OpenTelemetry opcional.

Específico de arXiv:

• Solo lectura, sin autenticación requerida — la API de arXiv es gratuita, los metadatos son CC0
• Cola de solicitudes secuencial que respeta el retraso de rastreo de 3 segundos de arXiv; las respuestas de límite de tasa (429, o 200 OK con un cuerpo Rate exceeded.) fallan rápido con un tiempo de espera calculado por el servidor en lugar de reintentar a ciegas
• Cadena de respaldo de contenido: arxiv.org/html → ar5iv → extracción de texto de PDF, en ese orden — el campo source informa cuál respondió
• Taxonomía completa de categorías de arXiv incrustada como datos estáticos
• Espejo local opcional de metadatos OAI-PMH (SQLite + FTS5) — opt-in, elimina la exposición al límite de tasa para arxiv_search y arxiv_get_metadata. Ver Opcional: espejo local

Salida amigable para agentes:

• Procedencia en cada lectura — el campo arxiv_read_paper de source nombra qué artefacto upstream respondió; arxiv_search refleja la consulta efectiva para que los resultados sean reproducibles
• Fallo parcial elegante — arxiv_get_metadata devuelve artículos encontrados junto con una razón not_found[] tipada por fallo en lugar de fallar todo el lote
• Contratos de salida discriminados — enums tipados source y not_found[].reason permiten que los llamadores ramifiquen según datos, no según análisis de cadenas

Primeros pasos

Instancia pública alojada

Una instancia pública está disponible en https://arxiv.caseyjhand.com/mcp — sin instalación requerida. Apunta cualquier cliente MCP hacia ella vía Streamable HTTP:

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

Autoalojado / Local

Añade lo siguiente al archivo de configuración de tu cliente MCP.

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/arxiv-mcp-server@latest"]
    }
  }
}

O con npx (sin necesidad de Bun):

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/arxiv-mcp-server@latest"]
    }
  }
}

O con Docker:

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/arxiv-mcp-server:latest"]
    }
  }
}

Para Streamable HTTP, configura el transporte e inicia el servidor:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Requisitos previos

• Bun v1.4.0 o superior (o Node.js v24+).

Instalación

1. Clona el repositorio:

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

2. Navega al directorio:

cd arxiv-mcp-server

3. Instala las dependencias:

bun install

Configuración

Toda la configuración es opcional — el servidor funciona de fábrica con valores predeterminados sensatos.

Variable	Descripción	Predeterminado
ARXIV_API_BASE_URL	URL base de la API de arXiv.	https://export.arxiv.org/api
ARXIV_REQUEST_DELAY_MS	Retraso mínimo entre solicitudes a la API de arXiv (ms).	3000
ARXIV_CONTENT_TIMEOUT_MS	Tiempo de espera para obtener el cuerpo del artículo — renders HTML y descargas de PDF (ms).	30000
ARXIV_API_TIMEOUT_MS	Tiempo de espera para solicitudes de búsqueda/metadatos de la API (ms).	15000
ARXIV_MIRROR_ENABLED	Habilita el espejo local de metadatos OAI-PMH para búsqueda y metadatos.	false
ARXIV_MIRROR_PATH	Ruta SQLite para el espejo.	./data/arxiv-mirror.db
ARXIV_MIRROR_REFRESH_CRON	Expresión cron UTC para la actualización diaria en proceso (solo modo HTTP).	sin definir
ARXIV_MIRROR_FALLBACK_LIVE	Recurre a la API en vivo si falla la búsqueda local por ID.	true
ARXIV_MIRROR_RECENT_DAYS_LIVE	Los valores positivos enrutan cada sort_by=submitted de consulta descendente a la API en vivo; 0 desactiva la omisión.	2
ARXIV_MIRROR_OAI_BASE_URL	URL base del endpoint OAI-PMH de arXiv.	https://oaipmh.arxiv.org/oai
ARXIV_MIRROR_OAI_REQUEST_DELAY_MS	Retraso mínimo entre solicitudes OAI-PMH (ms).	3000
ARXIV_MIRROR_REFRESH_TIMEOUT_MS	Presupuesto de cancelación para un subproceso de actualización programada (ms).	7200000
MCP_TRANSPORT_TYPE	Transporte: stdio o http.	stdio
MCP_HTTP_PORT	Puerto para el servidor HTTP.	3010
MCP_SESSION_MODE	auto, stateful o stateless. El servidor declara stateless en src/index.ts — no mantiene estado por sesión — por lo que cada ruta de ejecución se resuelve igual a menos que esta variable lo anule.	stateless
MCP_AUTH_MODE	Modo de autenticación: none, jwt o oauth.	none
MCP_LOG_LEVEL	Nivel de registro (RFC 5424).	info
OTEL_ENABLED	Habilita la instrumentación OpenTelemetry (spans, métricas, registros de finalización).	false

Ver .env.example para la lista completa de anulaciones opcionales.

Ejecutar el servidor

Desarrollo local

• Compilar y ejecutar:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• Ejecutar verificaciones y pruebas:

  bun run devcheck   # Lint, format, typecheck, security audit
  bun run test       # Vitest test suite
  

Opcional: espejo local

Para implementaciones autoalojadas detrás de una única IP de salida, el retraso de rastreo de ~3 segundos de arXiv serializa a los usuarios concurrentes. Un espejo local opcional elimina esa exposición al límite de tasa para arxiv_search y arxiv_get_metadata sirviendo desde un almacén SQLite + FTS5 recolectado vía OAI-PMH. arxiv_read_paper siempre usa la API en vivo — la recolección de contenido completo va contra la política de datos de arXiv.

Deshabilitado por defecto. Para habilitarlo:

# 1. Cold-start harvest (~4.4h sequential, resumable from checkpoint). One-time per installation.
bun run mirror:init

# 2. Enable the mirror.
export ARXIV_MIRROR_ENABLED=true

# 3. Start the server — reads switch to the mirror once the harvest completes.
bun run start:http

Mantenlo actualizado con bun run mirror:refresh (conéctalo a cron/systemd/launchd, o configura ARXIV_MIRROR_REFRESH_CRON para programarlo en proceso en modo HTTP) y verifica la integridad con bun run mirror:verify. Un servidor más nuevo migra el esquema de un espejo existente en el lugar al primer abrir — nunca una recolección nueva — y una actualización que reconstruye el índice de texto completo hace que ese primer inicio sea notablemente más lento en un espejo de corpus completo; mirror:verify informa la versión del esquema y sale con código no cero si una migración no se completó.

La clasificación BM25 de FTS5 difiere de la clasificación de relevancia propia de arXiv, por lo que sort_by=relevance devuelve un top-K diferente contra el espejo que contra la API en vivo. El espejo sirve solo la versión más reciente de cada artículo — una solicitud con versión fijada recurre a la API en vivo. Una actualización obsoleta o fallida sigue sirviendo la última recolección completada en lugar de caer a la API en vivo a mitad de solicitud.

Docker

docker build -t arxiv-mcp-server .
docker run --rm -p 3010:3010 arxiv-mcp-server

El Dockerfile usa por defecto transporte HTTP, modo de sesión sin estado y registra en /var/log/arxiv-mcp-server. Las dependencias pares de OpenTelemetry se instalan por defecto — compila con --build-arg OTEL_ENABLED=false para omitirlas.

Estructura del proyecto

Directorio	Propósito
src/index.ts	createApp() punto de entrada — registra herramientas/recursos e inicia el programador opcional de actualización del espejo.
src/config	Análisis y validación de variables de entorno específicas del servidor con Zod.
src/mcp-server/tools/definitions	Definiciones de herramientas (*.tool.ts).
src/mcp-server/resources/definitions	Definiciones de recursos (*.resource.ts).
src/services/arxiv	ArxivService — cliente de la API de arXiv en vivo (búsqueda, metadatos, HTML).
src/services/arxiv/mirror	Espejo OAI-PMH opcional — recolector, almacenamiento SQLite + FTS5, traductor de consultas, ejecutor.
scripts/arxiv-mirror-*.ts	Scripts del ciclo de vida del espejo (init, refresh, verify).
tests/	Pruebas unitarias y de integración.
docs/	Documento de diseño y estructura de directorios.

Guía de desarrollo

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

• Los manejadores lanzan excepciones, el framework las captura — sin try/catch en la lógica de herramientas
• Usa ctx.log para registro con ámbito de solicitud, ctx.state para almacenamiento con ámbito de inquilino
• La API de arXiv devuelve HTTP 200 para todo — incluidos los límites de tasa — así que verifica el tipo de contenido y el cuerpo antes de analizar
• Valida las respuestas crudas de arXiv → normaliza a tipos de dominio → devuelve el esquema de salida; nunca inventes campos faltantes

Contribuciones

Las incidencias son bienvenidas. Ejecuta las comprobaciones antes de enviar:

bun run devcheck
bun run test

Licencia

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