JinaAI

MCP ligero de JINA AI

GitHub

Prueba este MCPPatrocinado

Documentación

THIS IS ARCHIVE Encuentra un mejor sucesor: https://github.com/ciborro/webskim

Servidor MCP de Jina

Servidor del Protocolo de Contexto de Modelo (MCP) para las APIs de Reader y Search de Jina.AI.

Versión 1.0.0

Un servidor MCP ligero y eficiente para las APIs de Jina.AI

✅ 9 herramientas MCP completamente probadas
✅ Soporte completo para las APIs de Reader y Search
✅ Opciones avanzadas de filtrado y extracción
✅ Operaciones paralelas con manejo de solicitudes concurrentes
✅ Manejo integral de errores y registro de actividades
✅ Reducción del 50% en tokens frente a implementaciones alternativas
✅ Listo para producción con documentación completa

Documentación

Inicio rápido - Ponte en marcha en 5 minutos
Manejo de errores y solución de problemas - Problemas comunes y soluciones

Descripción general

Este servidor MCP proporciona 9 herramientas para interactuar con las APIs de Jina.AI:

Herramientas de la API Reader (5)

primer - Obtener el estado del servidor e información del sistema
read_url - Extraer contenido de una URL
capture_screenshot_url - Capturar una captura de pantalla de una página web
guess_datetime_url - Detectar la fecha de publicación de una URL
parallel_read_url - Leer múltiples URLs de forma concurrente

Herramientas de la API Search (4)

search_web - Realizar búsqueda web con filtrado avanzado
search_arxiv - Buscar artículos académicos en ArXiv
search_images - Buscar imágenes
parallel_search_web - Realizar múltiples búsquedas web de forma concurrente

Instalación e inicio rápido

Clonar e instalar

# Clone the repository
git clone https://github.com/ciborro/jina-light-mcp.git
cd jina-mcp-server

# Install dependencies
npm install

# Build TypeScript
npm run build

# Install globally (optional)
npm install -g .

Verificar la instalación

# Check if installed globally
which jina-mcp-server

# Start the server
npm start

Deberías ver:

[INFO] Jina MCP Server starting...
[INFO] Registered 9 tools
[OK] Jina MCP Server running on stdio transport

Para instrucciones de configuración detalladas, consulta la Guía de inicio rápido.

Configuración

Establece tu clave de API

Crea un archivo .env en la raíz del proyecto con tu clave de API de Jina:

echo "JINA_API_KEY=your_api_key_here" > .env

O edita el archivo .env directamente:

JINA_API_KEY=jina_xxxxxxxxxxxxxxxxxxxxx

Puedes obtener una clave de API gratuita en https://jina.ai/api

Uso

Pruebas locales con MCP Inspector

npm run dev

El servidor se iniciará en el transporte stdio. En otra terminal, usa mcp-cli o MCP Inspector para probar:

npx @modelcontextprotocol/inspector npx npm start

Esto abre una interfaz web en http://localhost:5173 donde puedes probar cada herramienta.

Integración con Claude Desktop (Local)

Añade a ~/Library/Application\ Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jina-mcp-local": {
      "command": "npm",
      "args": ["start"],
      "cwd": "/path/to/jina-mcp-server",
      "env": {
        "JINA_API_KEY": "your_jina_api_key_here"
      }
    }
  }
}

Reemplaza /path/to/jina-mcp-server con tu directorio de instalación real (por ejemplo, /Users/yourname/projects/jina-mcp-server o /home/yourname/jina-mcp-server).

Luego reinicia Claude Desktop. Las 9 herramientas aparecerán en Claude.

Referencia de la API

Herramienta: `primer`

Obtener el estado del servidor y la hora actual.

Parámetros: Ninguno

Ejemplo de respuesta:

Server Status: ✅ Online
Version: 1.0.0
Current Time: 11/9/2025, 5:45 PM
Timezone: America/New_York

Jina MCP Server is ready to serve requests.

Herramienta: `read_url`

Leer y extraer contenido de texto de una URL con opciones avanzadas de extracción.

Parámetros:

url (cadena, obligatorio): La URL a leer
timeout (número, opcional): Tiempo de espera de la solicitud en milisegundos (predeterminado: 30000)
locale (cadena, opcional): Configuración regional del navegador (por ejemplo, "en-US", "pl-PL")
instruction (cadena, opcional): Instrucción personalizada para la extracción de contenido
targetSelector (cadena, opcional): Selector CSS para extraer un elemento específico
removeSelector (cadena, opcional): Selectores CSS para eliminar (separados por comas)
waitForSelector (cadena, opcional): Selector CSS para esperar antes de la extracción
retainImages (cadena, opcional): Cómo manejar las imágenes - "all", "none" o "markdown" (predeterminado: "markdown")
retainLinks (cadena, opcional): Cómo manejar los enlaces - "all", "none" o "markdown" (predeterminado: "markdown")
withImagesSummary (booleano, opcional): Incluir resumen de imágenes
withLinksSummary (booleano, opcional): Incluir resumen de enlaces
proxy (cadena, opcional): URL del servidor proxy
userAgent (cadena, opcional): Cadena de User-Agent personalizada
jsonSchema (cadena, opcional): Esquema JSON para salida estructurada

Ejemplo:

{
  "url": "https://example.com",
  "timeout": 30000,
  "locale": "en-US",
  "retainImages": "markdown",
  "retainLinks": "markdown"
}

Herramienta: `capture_screenshot_url`

Capturar una captura de pantalla de una página web.

Parámetros:

url (cadena, obligatorio): La URL para capturar
fullPage (booleano, opcional): Capturar página completa (true) o primera pantalla (false, predeterminado)

Ejemplo:

{
  "url": "https://example.com",
  "fullPage": true
}

Devuelve: Datos de imagen codificados en Base64

Herramienta: `guess_datetime_url`

Detectar la fecha de publicación de una página web.

Parámetros:

url (cadena, obligatorio): La URL a analizar

Devuelve:

publication_date: Fecha detectada (ISO 8601)
accuracy: Nivel de confianza (alto/medio/desconocido)

Herramienta: `parallel_read_url`

Leer múltiples URLs de forma concurrente con opciones avanzadas de extracción.

Parámetros:

urls (matriz de cadenas, obligatorio): URLs a leer
maxParallel (número, opcional): Máximo de solicitudes concurrentes (1-10, predeterminado: 5)
timeout (número, opcional): Tiempo de espera de la solicitud en milisegundos (predeterminado: 30000)
locale (cadena, opcional): Configuración regional del navegador (por ejemplo, "en-US", "pl-PL")
instruction (cadena, opcional): Instrucción personalizada para la extracción de contenido
targetSelector (cadena, opcional): Selector CSS para extraer un elemento específico
retainImages (cadena, opcional): Cómo manejar las imágenes - "all", "none" o "markdown"
retainLinks (cadena, opcional): Cómo manejar los enlaces - "all", "none" o "markdown"

Ejemplo:

{
  "urls": ["https://example1.com", "https://example2.com"],
  "maxParallel": 3,
  "retainImages": "markdown",
  "retainLinks": "markdown"
}

Herramienta: `search_web`

Realizar una búsqueda web con opciones avanzadas de filtrado y localización.

Parámetros:

query (cadena, obligatorio): Consulta de búsqueda (por ejemplo, "inteligencia artificial")
count (número, opcional): Número de resultados a devolver (predeterminado: 10, máximo: 20)
location (cadena, opcional): Código de país para geolocalización (por ejemplo, "US", "PL", "GB")
language (cadena, opcional): Código de idioma para los resultados (por ejemplo, "en", "pl", "de")
site (cadena, opcional): Filtrar resultados a un dominio específico (por ejemplo, "github.com")
page (número, opcional): Número de página para paginación (predeterminado: 1)
filetype (cadena, opcional): Filtrar por tipo de archivo (por ejemplo, "pdf", "doc", "xlsx")
intitle (cadena, opcional): Buscar solo en títulos de página
timeout (número, opcional): Tiempo de espera de la solicitud en milisegundos (predeterminado: 30000)
provider (cadena, opcional): Proveedor de búsqueda ("google", "bing", etc.)

Ejemplos:

{
  "query": "machine learning",
  "count": 10,
  "language": "en",
  "location": "US"
}

Búsqueda con filtro de sitio:

{
  "query": "neural networks",
  "site": "github.com",
  "count": 5
}

Búsqueda con filtro de tipo de archivo:

{
  "query": "research paper",
  "filetype": "pdf",
  "language": "en",
  "count": 5
}

Herramienta: `search_arxiv`

Buscar artículos académicos en ArXiv.

Parámetros:

query (cadena, obligatorio): Consulta de búsqueda
maxResults (número, opcional): Máximo de artículos a devolver (predeterminado: 10)

Herramienta: `search_images`

Buscar imágenes.

Parámetros:

query (cadena, obligatorio): Consulta de búsqueda de imágenes
count (número, opcional): Número de imágenes (predeterminado: 20)

Herramienta: `parallel_search_web`

Realizar múltiples búsquedas web de forma concurrente con opciones avanzadas de filtrado.

Parámetros:

queries (matriz de cadenas, obligatorio): Consultas a buscar
maxParallel (número, opcional): Máximo de búsquedas concurrentes (1-10, predeterminado: 5)
count (número, opcional): Número de resultados por consulta (predeterminado: 10)
location (cadena, opcional): Código de país para geolocalización (por ejemplo, "US", "PL")
language (cadena, opcional): Código de idioma para los resultados (por ejemplo, "en", "pl")
site (cadena, opcional): Filtrar resultados a un dominio específico
page (número, opcional): Número de página para paginación
filetype (cadena, opcional): Filtrar por tipo de archivo (por ejemplo, "pdf")
intitle (cadena, opcional): Buscar solo en títulos de página
timeout (número, opcional): Tiempo de espera de la solicitud en milisegundos
provider (cadena, opcional): Proveedor de búsqueda ("google", "bing", etc.)

Ejemplo:

{
  "queries": ["Jina AI", "Claude AI", "Anthropic"],
  "maxParallel": 3,
  "language": "en",
  "count": 5
}

Operadores de consulta de búsqueda

Usa estos operadores en el parámetro query de search_web y parallel_search_web para filtrar resultados:

Operador	Ejemplo	Propósito
`site:`	`site:github.com machine learning`	Buscar solo en un dominio específico
`intitle:`	`intitle:"machine learning" tutorial`	Buscar solo en títulos de página
`filetype:`	`machine learning filetype:pdf`	Filtrar por tipo de archivo
`ext:`	`tutorial ext:docx`	Filtrar por extensión de archivo

Ejemplos

Buscar proyectos de Python en GitHub:

{
  "query": "site:github.com python projects",
  "count": 10
}

Encontrar artículos de investigación en PDF:

{
  "query": "deep learning filetype:pdf",
  "language": "en",
  "count": 5
}

Combinar múltiples operadores:

{
  "query": "site:github.com intitle:tutorial python",
  "location": "US",
  "language": "en",
  "count": 10
}

Manejo de errores

Errores de clave de API

Si la clave de API falta o no es válida, verás:

🔑 Authentication Error: Invalid or missing API key.
Make sure your Jina API key is configured in .env

Límite de velocidad

Si se excede el límite de velocidad (500 RPM para titulares de clave de API):

⏱️ Rate Limit: Too many requests. Please wait and retry.

Errores de red

Los errores de conexión y tiempo de espera se capturan y se informan con detalles.

Estructura del proyecto

mcp-server/
├── src/
│   ├── index.ts              # Main MCP server + tool handlers
│   ├── utils/
│   │   ├── api-client.ts      # Jina API client with error handling
│   │   ├── reader.ts          # Reader API functions (copied from test-jina-api)
│   │   ├── search.ts          # Search API functions (copied from test-jina-api)
│   │   ├── error-handler.ts   # MCP error formatting
│   │   └── yaml-formatter.ts  # Response formatting utility
│   └── types/
│       └── jina.ts            # TypeScript type definitions
├── dist/                      # Compiled JavaScript
├── package.json
├── tsconfig.json
├── .gitignore                  # Git ignore patterns
└── .env.example               # Example environment file (copy to .env to use)

Desarrollo

Compilar

npm run build

Ejecutar

npm run dev

Limpiar

npm run clean

Pruebas

Probar la API Reader (sin autenticación requerida)

curl https://r.jina.ai/https://example.com

Probar la API Search (requiere autenticación)

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://s.jina.ai/search?q=test"

Características y capacidades

Características de la API Reader

✅ Extracción de contenido de cualquier URL
✅ Selectores CSS para extracción dirigida
✅ Múltiples formatos de salida (markdown, html, text)
✅ Control de manejo de imágenes y enlaces
✅ Soporte de User-Agent personalizado y proxy
✅ Lectura paralela de URLs (hasta 10 concurrentes)

Características de la API Search

✅ Búsqueda web con hasta 20 resultados
✅ Filtrado por dominio (operador site:)
✅ Filtrado por título (operador intitle:)
✅ Filtrado por tipo de archivo (operador filetype:)
✅ Localización geográfica (parámetro gl)
✅ Filtrado por idioma (parámetro hl)
✅ Soporte de paginación (parámetro page)
✅ Búsqueda paralela (hasta 10 concurrentes)
✅ Múltiples proveedores de búsqueda (Google, Bing, etc.)

Limitaciones

API Reader: Nivel gratuito (20 RPM sin clave, 500 RPM con clave)
API Search: Requiere clave de API válida (límite de 500 RPM)
Resultados de búsqueda: Máximo 20 resultados por consulta
Operaciones paralelas: Máximo 10 solicitudes concurrentes por lote
Datos de imagen: Devueltos como cadena base64
Tiempos de espera: Máximo 180 segundos por solicitud

Límites de velocidad

API Reader: 20 RPM sin clave, 500 RPM con clave
API Search: 500 RPM con clave

Implementa lógica de retroceso y reintento si se alcanzan los límites.

Solución de problemas

"Extensión de archivo desconocida .ts"

Asegúrate de haber compilado el proyecto:

npm run build

"No se puede encontrar el módulo"

Reinstala las dependencias:

rm -rf node_modules package-lock.json
npm install

El servidor no se inicia

Comprueba que el archivo .env existe y tiene un JINA_API_KEY válido:

cat .env

Las herramientas no aparecen en Claude

Reinicia Claude Desktop
Comprueba la sintaxis JSON de la configuración
Verifica que la ruta cwd sea correcta

Registro de cambios

Versión 1.0.0 (Actual)

✅ 9 herramientas MCP completamente implementadas
✅ API Reader completa con extracción avanzada de contenido
✅ API Search completa con filtrado y paginación
✅ Parámetros de filtrado avanzados (site, language, filetype, intitle, page, provider)
✅ Parámetros de extracción avanzados (locale, instruction, selectores CSS, control de imágenes/enlaces)
✅ Operaciones paralelas para lectura y búsqueda (hasta 10 concurrentes)
✅ Manejo integral de errores y registro de actividades
✅ Documentación completa con ejemplos y solución de problemas
✅ Código listo para producción

Qué se incluye

✅ Características listas para producción

9 herramientas MCP - Todas completamente implementadas y probadas
API Reader - Extracción de contenido con selectores CSS avanzados, control de imágenes/enlaces, soporte de configuración regional
API Search - Búsqueda web, de imágenes y ArXiv con filtrado y paginación
Operaciones paralelas - Lectura y búsqueda concurrente de URLs (hasta 10 concurrentes)
Manejo de errores - Mensajes de error integrales para errores de API, red y validación
Soporte de límite de velocidad - Maneja 500 RPM (con clave de API)
Configuración de entorno - Configuración fácil con variables de entorno
Documentación completa - Guía de inicio rápido, ejemplos de configuración y solución de problemas

Beneficios de rendimiento

Reducción del 50% en tokens - Esta implementación usa significativamente menos tokens que las implementaciones alternativas
Uso eficiente de la API - Manejo optimizado de solicitudes y procesamiento de respuestas
Tiempos de respuesta rápidos - Sobrecarga mínima en la ejecución de herramientas

Licencia

MIT

Soporte

Para problemas con las APIs de Jina.AI, consulte: https://docs.jina.ai
Para la especificación de MCP, consulte: https://modelcontextprotocol.io

JinaAI

Documentación

Servidor MCP de Jina

Versión 1.0.0

Documentación

Descripción general

Herramientas de la API Reader (5)

Herramientas de la API Search (4)

Instalación e inicio rápido

Clonar e instalar

Verificar la instalación

Configuración

Establece tu clave de API

Uso

Pruebas locales con MCP Inspector

Integración con Claude Desktop (Local)

Referencia de la API

Herramienta: primer

Herramienta: read_url

Herramienta: capture_screenshot_url

Herramienta: guess_datetime_url

Herramienta: parallel_read_url

Herramienta: search_web

Herramienta: search_arxiv

Herramienta: search_images

Herramienta: parallel_search_web

Operadores de consulta de búsqueda

Ejemplos

Manejo de errores

Errores de clave de API

Límite de velocidad

Errores de red

Estructura del proyecto

Desarrollo

Compilar

Ejecutar

Limpiar

Pruebas

Probar la API Reader (sin autenticación requerida)

Probar la API Search (requiere autenticación)

Características y capacidades

Características de la API Reader

Características de la API Search

Limitaciones

Límites de velocidad

Solución de problemas

"Extensión de archivo desconocida .ts"

"No se puede encontrar el módulo"

El servidor no se inicia

Las herramientas no aparecen en Claude

Registro de cambios

Versión 1.0.0 (Actual)

Qué se incluye

✅ Características listas para producción

Beneficios de rendimiento

Licencia

Soporte

Herramienta: `primer`

Herramienta: `read_url`

Herramienta: `capture_screenshot_url`

Herramienta: `guess_datetime_url`

Herramienta: `parallel_read_url`

Herramienta: `search_web`

Herramienta: `search_arxiv`

Herramienta: `search_images`

Herramienta: `parallel_search_web`