arXiv Research MCP

Un servidor MCP de solo lectura y desplegable para la investigación de literatura científica.

ChatGPT
   ↓  Streamable HTTP
arXiv Research MCP
   ↓  official Atom API
arXiv scientific papers

El servidor recupera y normaliza metadatos. ChatGPT sigue siendo responsable de explicar la física, comparar artículos y resolver ecuaciones.

Herramientas

Cada herramienta está marcada como de solo lectura y devuelve datos estructurados tipados que contienen el ID de arXiv, el título y el resumen normalizados, autores, categorías, fechas, DOI, referencia de la revista, URL del resumen y URL del PDF cuando estén disponibles.

Configuración local

Requiere Python 3.11 o superior.

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
Copy-Item .env.example .env

Edita ARXIV_USER_AGENT en .env y sustituye el contacto de ejemplo por tu correo electrónico o la URL del proyecto. arXiv no requiere una clave de API.

Ejecuta localmente a través de stdio:

arxiv-mcp

Ejecuta localmente el transporte compatible con el modo remoto:

arxiv-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Los endpoints son:

http://127.0.0.1:8000/mcp
http://127.0.0.1:8000/health

Para probar una herramienta manualmente, inicia el servidor HTTP, ejecuta el MCP Inspector oficial y conéctalo a http://127.0.0.1:8000/mcp:

npx @modelcontextprotocol/inspector@latest

Ejecutar pruebas

pytest
ruff check .

Las pruebas usan respuestas HTTP simuladas y no consumen la API de arXiv. GitHub Actions ejecuta las mismas comprobaciones en cada push y pull request.

Fiabilidad y seguridad

• Upstream fijo en la lista de permitidos: https://export.arxiv.org/api/query

• Espaciado global de solicitudes de tres segundos por defecto

• Reintentos limitados para tiempos de espera, fallos de red, HTTP 429 y respuestas 5xx temporales

• Validación estricta de resultados, offset, categoría, ordenación e ID de arXiv

• Análisis XML seguro con entidades externas deshabilitadas

• Sin ejecución de shell, obtención arbitraria de URLs, secretos, operaciones de escritura ni almacenamiento de datos de usuario

• Despliegue Streamable HTTP sin estado

Desplegar en Render

El repositorio incluye un Dockerfile no root y un Blueprint render.yaml.

1. Sube este repositorio a GitHub.

2. Inicia sesión en Render y selecciona Nuevo → Blueprint.

3. Conecta el repositorio de GitHub y aplica render.yaml.

4. En el entorno del servicio de Render, cambia ARXIV_USER_AGENT para que incluya tu correo electrónico real o la URL del repositorio.

5. Espera a que /health pase correctamente y luego copia la URL del servicio.

La URL final del MCP es:

https://<your-render-service>.onrender.com/mcp

El Blueprint usa la instancia gratuita de Render, por lo que el despliegue no crea silenciosamente un compromiso de facturación. Render documenta que los servicios gratuitos entran en reposo después de 15 minutos de inactividad y pueden tardar alrededor de un minuto en reiniciarse. Ese arranque en frío puede superar el tiempo de espera de un cliente MCP; mejora el servicio a starter o a otra instancia de pago antes de depender de él como conector de producción siempre disponible. Consulta las limitaciones del plan gratuito de Render y la referencia de Blueprint.

Conectar con ChatGPT

Estos pasos siguen la documentación oficial actual de OpenAI:

1. Despliega el servidor y confirma que la URL HTTPS pública /mcp funciona en MCP Inspector.

2. En ChatGPT, abre Configuración → Seguridad e inicio de sesión y habilita el Modo de desarrollador.

3. Abre ChatGPT Plugins y selecciona el botón +.

4. Introduce:

   • Nombre: arXiv Research

   • Descripción: Read-only search and metadata retrieval from the official arXiv API.

   • Conexión: endpoint MCP público

   • URL del servidor: https://<your-render-service>.onrender.com/mcp

   • Autenticación: ninguna

5. Crea la conexión y confirma que se detectan exactamente cinco herramientas.

6. Inicia un nuevo chat y añade arXiv Research desde el menú de herramientas.

OpenAI actualmente requiere un endpoint HTTPS público (o su Secure MCP Tunnel) y Streamable HTTP, normalmente en /mcp. La disponibilidad del modo de desarrollador depende de la política de la cuenta y del espacio de trabajo. La página actual de OpenAI no lo promete para todos los planes concretos de ChatGPT, por lo que la presencia del interruptor de modo de desarrollador en tu cuenta es la verificación definitiva. Si una cuenta Plus no lo muestra, el servidor sigue siendo utilizable a través de MCP Inspector, otro cliente MCP o el OpenAI API Playground. Consulta la guía de conexión actual de OpenAI y la guía de servidores MCP.

Ejemplos de prompts para ChatGPT

• Search arXiv for recent quantum gravity papers.

• Find papers about the Bondi-Sachs formalism.

• Search hep-th for path integral approaches to gravity.

• Find papers by Roger Penrose related to general relativity.

• Get the metadata and PDF link for arXiv:2401.12345.

Estructura del proyecto

.
├── src/arxiv_mcp/
│   ├── arxiv_client.py
│   ├── config.py
│   ├── models.py
│   └── server.py
├── tests/
├── .github/workflows/ci.yml
├── .env.example
├── Dockerfile
├── render.yaml
├── pyproject.toml
└── README.md

Con licencia MIT.