arxiv-mcp-server

Servidor público alojado: https://arxiv.caseyjhand.com/mcp

Herramientas

Cuatro herramientas para buscar y leer artículos de arXiv:

arxiv_search

Busca artículos mediante consultas de texto libre con prefijos de campo y operadores booleanos.

• Prefijos de campo: ti: (título), au: (autor), abs: (resumen), cat: (categoría), all: (todos los campos)

• Operadores booleanos: AND, OR, ANDNOT

• Filtro de categoría opcional, ordenación (relevancia, fecha de envío, fecha de actualización) y paginación

• La categoría acepta un código hoja (cs.CL) o un archivo completo (astro-ph, cs, math) — un archivo sin subdividir cubre sus clases temáticas más los artículos planos heredados registrados antes de su subdivisión

• submitted_from / submitted_to acotan la fecha de envío (inclusive, UTC YYYY-MM-DD). Las ventanas consecutivas cubren las coincidencias sin dejar huecos — un artículo enviado exactamente en el límite de medianoche aparece en ambas, así que deduplica por ID — que es como se llega a resultados más allá del límite de paginación de 10 000

• Devuelve la consulta tal como se buscó realmente, con todos los filtros incorporados — reproducirla genera el mismo conjunto de resultados

• Devuelve hasta 50 resultados por solicitud con metadatos completos, incluido el resumen

arxiv_get_metadata

Obtén metadatos completos de uno o más artículos por ID de arXiv conocido.

• Obtención por lotes de hasta 10 artículos en una sola solicitud

• Acepta IDs versionados (2401.12345v2) y no versionados (2401.12345)

• Formato de ID heredado compatible (hep-th/9901001)

• Informa de los IDs no encontrados por separado de los artículos encontrados

arxiv_read_paper

Lee el cuerpo completo de un artículo de arXiv.

• Prueba primero el HTML nativo de arXiv, luego ar5iv y después el texto extraído del PDF — el campo source indica cuál respondió

• Elimina la cabecera HTML y el material repetitivo, y convierte MathML a LaTeX delimitado por dólares ($…$ en línea, $$…$$ en bloque) para que el presupuesto de caracteres se destine al contenido del artículo

• Devuelve HTML sin procesar — sin análisis ni extracción; el LLM interpreta el contenido directamente. Los cuerpos extraídos del PDF son texto plano: la prosa es fiable, pero las matemáticas, las tablas y la estructura de encabezados se aplanan

• max_characters tiene un valor predeterminado de 100 000; pasa null para obtener el artículo completo en una sola llamada. El HTML sin procesar puede ocupar de 500 KB a más de 3 MB en artículos con muchas matemáticas, más de lo que la mayoría de los clientes aceptan en un solo resultado de herramienta — pagina con start en su lugar

arxiv_list_categories

Lista los códigos y nombres de categorías de arXiv para descubrimiento.

• ~155 categorías en 8 grupos de nivel superior (cs, math, physics, q-bio, q-fin, stat, eess, econ)

• Filtro de grupo opcional para acotar los resultados

• Datos estáticos — siempre tiene éxito

Related MCP server: Research Server

Recursos

Características

Construido sobre @cyanheads/mcp-ts-core:

• Definiciones declarativas de herramientas — un solo 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)

• Registro estructurado con trazado OpenTelemetry opcional

• Se ejecuta localmente (stdio/HTTP) desde el mismo código base

Específico de arXiv:

• Solo lectura, sin autenticación necesaria — la API de arXiv es gratuita y los metadatos son CC0

• Cola de solicitudes con límite de velocidad que aplica el retardo de rastreo de 3 segundos de arXiv

• Enfriamiento adaptativo ante límite de velocidad (5s → 10s → 20s → 30s), respeta Retry-After

• Reintentos con retroceso exponencial para fallos transitorios

• Cadena de respaldo de contenido: HTML nativo de arXiv → ar5iv → extracción de texto del PDF (ambos renderizados HTML usan LaTeXML, por lo que tienden a fallar juntos; el PDF es el artefacto que todo artículo tiene, y también cubre una caída de ar5iv en lugar de dejar fallar la lectura)

• Taxonomía completa de categorías de arXiv incluida como datos estáticos

• Espejo local opcional de metadatos OAI-PMH (SQLite + FTS5) — opcional, elimina la exposición al límite de velocidad para arxiv_search y arxiv_get_metadata. Ver Opcional: Espejo local.

Primeros pasos

Instancia pública alojada

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

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

Autohospedado / Local

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

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

Requisitos previos

• Bun v1.3.0 o superior.

Instalación

1. Clona el repositorio:

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

2. Entra en el directorio:

cd arxiv-mcp-server

3. Instala las dependencias:

bun install

Configuración

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

Ejecutar el servidor

Desarrollo local

• Compilar y ejecutar:

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

• Ejecutar comprobaciones y pruebas:

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

Opcional: Espejo local

Para implementaciones autohospedadas detrás de una única IP de salida, el retardo de rastreo de ~3 segundos por IP de arXiv serializa a los usuarios concurrentes. Un espejo local opcional elimina la exposición al límite de velocidad para arxiv_search y arxiv_get_metadata al servir desde un almacén SQLite + FTS5 recopilado mediante OAI-PMH. arxiv_read_paper sigue usando la API en vivo — la recopilación de contenido completo está prohibida por 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

Actualización incremental diaria (delta pequeña; la duración depende del ritmo de paginación OAI-PMH de arXiv) mediante:

bun run mirror:refresh   # wire to cron / systemd timer / launchd, OR
                         # set ARXIV_MIRROR_REFRESH_CRON to schedule it in HTTP mode (spawned as a child process)
bun run mirror:verify    # schema version + PRAGMA integrity_check / quick_check

Schema upgrades. El espejo registra una versión de esquema y se migra a sí mismo en el sitio la primera vez que un servidor más reciente lo abre: nunca una re-cosecha, y nunca un paso de operador separado. La actualización que añadió comment y journal_ref al índice de texto completo (#37) reconstruye ese índice a partir de las filas ya almacenadas, de modo que las búsquedas co: y jr: se resuelven contra un espejo cosechado antes de esa actualización. La reconstrucción se ejecuta al inicio, antes de que el almacén responda a su primera lectura, y registra líneas de progreso mirror migration v2→v3 (fts rebuild) a lo largo de todo el proceso; en un espejo de corpus completo, espera que el primer arranque después de la actualización tarde notablemente más de lo habitual. Una reconstrucción interrumpida se repite en la siguiente apertura en lugar de dejarse a medio aplicar. bun run mirror:verify imprime la versión de esquema que lleva el archivo y sale con un código distinto de cero si una migración nunca se completó.

Behavior notes. Divergencia de clasificación: FTS5 BM25 difiere de la clasificación interna de arXiv, por lo que sortBy=relevance contra el espejo devuelve un top-K diferente al de la API en vivo. Las consultas ordenadas por submitted de forma descendente dentro de los días ARXIV_MIRROR_RECENT_DAYS_LIVE se enrutan a la API en vivo para cubrir la brecha de la actualización nocturna. Resiliencia de la actualización: después de que se complete la cosecha inicial en frío, una actualización diaria en curso o fallida sigue sirviendo el conjunto de datos existente desde el espejo; arxiv_search y arxiv_get_metadata no recurren a la API en vivo durante la ventana de actualización (#21). La actualización programada en modo HTTP se ejecuta en un proceso hijo, por lo que las escrituras síncronas de SQLite de la cosecha nunca bloquean el bucle de eventos de las solicitudes: la búsqueda y los metadatos siguen respondiendo con fluidez en todo momento (#22). El espejo almacena solo la última versión; las lecturas por versión continúan usando la API en vivo. Consulta #12 para el diseño completo.

Docker

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

Estructura del Proyecto

Guía de Desarrollo

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

• Los manejadores lanzan excepciones, el framework las captura: no hay try/catch en la lógica de las herramientas.

• Usa ctx.log para el registro específico del dominio.

• La limitación de tasa la gestiona ArxivService — no añadas retardos por herramienta.

• La API de arXiv devuelve HTTP 200 para todo: comprueba el content-type y el cuerpo de la respuesta.

Contribuciones

Las issues y las pull requests son bienvenidas. Ejecuta las comprobaciones antes de enviar:

bun run devcheck
bun test

Licencia

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