mistral-mcp

Servidor MCP de Mistral para extracción de documentos

Convierte facturas en texto o Markdown a JSON tipado mediante MCP. mistral-mcp utiliza Mistral chat para extraer proveedores, totales, líneas de detalle y fechas de vencimiento, y luego valida el esquema de la respuesta. El OCR opcional de Mistral maneja entradas PDF e imagen. process_document también admite contratos, documentos de identidad y clasificación automática. Hay seis herramientas disponibles por defecto, incluyendo chat, visión, transcripción y completado de código.

Français · Guía de migración · Ejemplos · Despliegue

Paquete npm · Notas de la versión 1.0.0 · Lanzamientos de GitHub · Documentación de la API de Mistral

Versión 1.0.0 — cambios importantes respecto a 0.11.0: core ahora expone seis herramientas; los clientes de orquestación existentes deben elegir un perfil explícito. Los resultados de documentos requieren extraction_source, y ocr_confidence / page_count pueden ser null. Instrucciones de migración y reversión.

Instalación en un cliente MCP

Requiere Node.js 20+, npm y una clave de API de Mistral con acceso y cuota para el modelo solicitado. Para clientes que usan mcpServers JSON, configure el servidor stdio:

{
  "mcpServers": {
    "mistral": {
      "command": "npx",
      "args": ["-y", "mistral-mcp@1.0.0"],
      "env": {
        "MISTRAL_API_KEY": "your_key_here",
        "MISTRAL_DEFAULT_MODEL": "ministral-3b-latest",
        "MISTRAL_MCP_PROFILE": "core"
      }
    }
  }
}

Esto ejecuta npx -y mistral-mcp@1.0.0. Reinicie el cliente y actualice su catálogo de herramientas. El servidor lee el entorno proporcionado por el cliente; no carga .env automáticamente. Use la configuración secreta de su cliente para la clave. ministral-3b-latest fue verificado en la cuenta de prueba; el acceso al modelo y la cuota gratuita dependen de su cuenta. Consulte sus límites antes de realizar llamadas. El alojamiento MCP local aún envía solicitudes de extracción a Mistral.

Inicio rápido: una factura existente en texto o Markdown

El script de factura y los fixtures son ejemplos de código fuente, no incluidos en el paquete npm. Consulte la etiqueta de lanzamiento y compile desde la raíz del repositorio:

git clone https://github.com/Swih/mistral-mcp.git
cd mistral-mcp
git checkout v1.0.0
npm ci
npm run build

Establezca la clave y el modelo de chat en su entorno o en un archivo local .env:

MISTRAL_API_KEY=your_key_here
MISTRAL_DEFAULT_MODEL=ministral-3b-latest

El ejemplo carga .env con dotenv. Mantenga la clave fuera del control de versiones. Elija un modelo de chat con cuota en su cuenta; el predeterminado puede tener cuota cero.

npm run example:invoice -- test/fixtures/invoice-text.md --output invoice-result.json

Esto utiliza la factura Markdown sintética. Para su propia factura existente en .txt o .md UTF-8, la sintaxis del comando es:

node examples/invoice.mjs <local-file.txt|local-file.md> [--output result.json]

El script lee el texto localmente y llama a process_document con source: { type: "text", text: "..." }, kind: "invoice" y options.cache: "bypass" a través del perfil core del servidor local. El texto debe contener contenido que no sea espacios en blanco y caber dentro de 60,000 unidades de código UTF-16 (longitud de cadena de JavaScript). Markdown y espacios en blanco se conservan sin cambios. No hay carga de archivos ni llamada OCR; la extracción de facturas envía el texto a Mistral chat. El ejemplo usa solo Mistral Cloud y aún requiere una clave y cuota de chat; el procesamiento no es completamente local ni garantizado gratuito. Consulte los límites de su cuenta.

Sin --output, imprime JSON validado; con él, escribe en un archivo nuevo e imprime esa ruta. Los archivos existentes no se sobrescriben. La ruta de salida se reserva antes de las llamadas API y puede permanecer vacía después de un fallo; elimínela o elija una nueva ruta antes de reintentar.

El 2026-09-28, la prueba de texto en vivo y el ejemplo CLI tuvieron éxito con ministral-3b-latest, usando solo chat. Los campos verificados fueron proveedor ACME SAS, total 12960 EUR, fecha de vencimiento 2026-09-11 y las cantidades, precios unitarios y montos de las tres líneas de factura. Esto verifica una factura sintética, no una puntuación general de precisión o confiabilidad.

Para un PDF o imagen, la ruta OCR existente sigue disponible:

npm run example:invoice -- test/fixtures/corpus/invoice-fr-table.pdf --output invoice-ocr-result.json

Los archivos PDF, PNG, JPEG y WebP de hasta 20 MiB requieren acceso y cuota de Files, OCR y chat. El script sube el archivo, llama a process_document e intenta eliminar la carga en finally, incluso después de un fallo de extracción. No hay sonda separada de preparación OCR. La carga y limpieza usan la API de Files sin exponer herramientas de administración en core. Limitación conocida: el HTTP 429 de la cuenta de prueba / cuota OCR cero bloqueó la validación OCR en vivo. La ejecución de texto exitosa no valida la extracción OCR.

Compare cualquier resultado extraído contra su fuente. El PDF sintético y la verdad de referencia del fixture describen el contenido esperado del documento, no la salida en vivo capturada. La validación de esquema verifica la forma y los tipos de la respuesta; no verifica la precisión factual, la aritmética de facturas, el tratamiento fiscal o la corrección contable. Revise los campos extraídos contra la fuente antes de usarlos.

Perfiles

MISTRAL_MCP_PROFILE selecciona uno de cinco perfiles. El predeterminado es core para Mistral Cloud; un MISTRAL_BASE_URL personalizado infiere self-hosted a menos que establezca un perfil explícitamente.

Perfil	Herramientas	Alcance en 1.0.0
core (predeterminado)	6	Documentos, chat, visión, transcripción y completado de código
metier-docs	17	Perfil heredado conservado: las seis herramientas principales más las 11 herramientas de orquestación; un superconjunto del núcleo antiguo de 16 herramientas
workflows	11	Flujos de trabajo, conectores y descubrimiento de índices de búsqueda
admin	46	Todas las herramientas implementadas por este servidor, incluyendo Files, Batch, Conversations y Libraries
self-hosted	5	Chat, chat en streaming, embeddings, llamada de funciones y visión en un endpoint compatible

full sigue siendo un alias obsoleto de admin, no un sexto perfil. Establezca MISTRAL_MCP_PROFILE=metier-docs para conservar el conjunto de herramientas principales antiguo después de actualizar; elija workflows para orquestación sola o admin para el conjunto completo de herramientas. Reinicie el servidor y actualice el descubrimiento de herramientas después de cambiar de perfil.

npx -y mistral-mcp@1.0.0 --doctor informa el perfil local y la lista de herramientas sin llamadas API. El recurso mistral://capabilities informa el endpoint activo, las familias de herramientas y las razones de las herramientas omitidas. Ninguno prueba acceso a cuenta o cuota.

Herramientas principales y comportamiento de documentos

Herramienta	Propósito
process_document	Texto/Markdown suministrado u OCR, clasificación opcional y extracción validada por esquema para facturas, contratos, documentos de identidad o texto genérico
mistral_ocr	Texto OCR crudo, tablas, anotaciones y bloques opcionales de PDFs o imágenes
mistral_vision	Chat con imágenes suministradas por URL o base64
mistral_chat	Completado de chat, incluyendo formatos de respuesta estructurados
voxtral_transcribe	Transcripción de audio con diarización de hablantes opcional
codestral_fim	Completado de código fill-in-the-middle

process_document acepta source: { type: "text", text: string }, una URL de documento, una imagen base64 o un ID de archivo subido. El texto puede contener Markdown y se conserva sin cambios; las cadenas en blanco o solo espacios en blanco y las cadenas por encima de 60,000 unidades de código UTF-16 se rechazan para cada kind, incluyendo generic. kind es auto (predeterminado), invoice, contract, id_document o generic. Las llamadas exitosas devuelven content legible y JSON structuredContent; los fallos devuelven isError: true.

Por ejemplo, estos son argumentos de herramienta usando entrada sintética, no un resultado en vivo:

{
  "source": {
    "type": "text",
    "text": "# Invoice DEMO-001\nVendor: Example Studio\nService: 2 hours at EUR 50\nTotal due: EUR 100\nDue date: 2026-10-15\n"
  },
  "kind": "invoice",
  "options": { "cache": "bypass" }
}

En un fallo de caché o con cache: "bypass", auto llama a chat para clasificar incluso una fuente de texto; invoice, contract y id_document usan chat para extracción tipada. kind: "generic" explícito con una fuente de texto hace cero llamadas API y devuelve el texto suministrado como tanto ocr_text como structured_text.

Cada resultado exitoso incluye estos campos:

Campo	Texto / Markdown suministrado	Fuente OCR exitosa
extraction_source (requerido)	"provided_text"	"mistral_ocr"
ocr_text (nombre conservado)	Texto de entrada original, sin cambios	Texto OCR
ocr_confidence	null	Número de 0 a 1
page_count	null	Número de páginas procesadas

• options.maxPages y options.minOcrConfidence se aplican solo a fuentes OCR. No paginan ni puntúan el texto suministrado. Para OCR, puntuaciones de confianza faltantes, incompletas o inválidas causan un error, al igual que puntuaciones por debajo del mínimo solicitado. El 0.3 predeterminado no se mide; la confianza OCR no establece precisión de extracción.
• Para fuentes OCR, options.maxPages predetermina a 50 (máximo 200). La extracción tipada rechaza texto OCR por encima de 60,000 unidades de código UTF-16: divida el documento o use generic para texto OCR. El límite de entrada de fuente de texto aún se aplica a generic. options.languageHints guía la extracción tipada, no el modelo OCR.
• options.cache: "bypass" omite lecturas y escrituras de caché. Otros modos son read_only y read_write. Los documentos de identidad omiten la caché por defecto, incluso después de la clasificación auto; read_write explícito los incluye.
• Los archivos de caché contienen contenido extraído. MISTRAL_MCP_CACHE_DIR establece la ubicación; MISTRAL_MCP_CACHE_TTL_HOURS predetermina a 168 horas (0 deshabilita la reutilización y nuevas escrituras). La limpieza es oportunista durante operaciones de caché. La omisión no borra entradas más antiguas, y la expiración no garantiza eliminación en un momento fijo. La versión de pipeline v1.0.0-text.1 invalida la reutilización de entradas de caché más antiguas; no garantiza su eliminación inmediata.

El corpus sintético separa el texto OCR requerido de los campos de factura extraídos esperados. npm run eval:docs evalúa estos por separado a través de llamadas API reales. La verdad del fixture no es un resultado de precisión en vivo; los PDFs sintéticos basados en texto no establecen precisión en escaneos degradados. Guía de desarrollo y evaluación.

Referencias de API y despliegue

mistral://capabilities describe el conjunto de herramientas activo. mistral://models lee el catálogo ascendente e informa fallback si la llamada API falla. mistral://voices está disponible en admin; mistral://workflows está disponible en metier-docs, workflows y admin. La presencia en el catálogo no establece acceso o cuota.

Puede alojar el proceso MCP y configurar su endpoint ascendente, credenciales, exposición de herramientas y política de caché. Por defecto, las solicitudes van a Mistral Cloud: el alojamiento MCP local no hace la inferencia de documentos local. Estos controles solos no establecen residencia de datos o cumplimiento regulatorio.

Un MISTRAL_BASE_URL personalizado infiere self-hosted: chat, chat en streaming, embeddings, llamada de funciones y visión, sujeto al soporte de endpoint/modelo. No incluye OCR ni process_document. Un perfil explícito anula la inferencia pero no agrega APIs faltantes a un backend.

Referencia	Contenido
Migración	Herramientas principales eliminadas, perfiles explícitos, fallback 0.11.0 fijado
Ejemplos	Facturas locales, transcripción y conversaciones respaldadas por biblioteca
Familias de herramientas y esquemas de entrada de herramientas MCP	Membresía completa de herramientas y referencia de argumentos
Prompts	Minutas de reuniones, respuestas de correo, commits, resúmenes legales, recordatorios de facturas y revisión de código
Despliegue y .env.example	Docker, Compose, Kubernetes, endpoints personalizados, caché y configuraciones HTTP
Guía de conector público	Despliegue HTTPS; las llamadas de conector público no se establecen como validadas de extremo a extremo aquí
Plugin de Claude Code	Plugin opcional con 11 habilidades, fijado a mistral-mcp@1.0.0
Contribución	Compilación, pruebas, evaluación y verificaciones de lanzamiento
Changelog y política de seguridad	Cambios e informes de seguridad
stdio es el transporte predeterminado. --http o MCP_TRANSPORT=http habilita
Streamable HTTP en 127.0.0.1:3333/mcp por defecto, con autenticación bearer configurable
y orígenes permitidos. No se proporciona OAuth integrado.
Los registros de auditoría de herramientas van a stderr y omiten argumentos y cargas de resultados;
MISTRAL_MCP_AUDIT=off los desactiva.

Las pruebas de la era del protocolo cubren MCP 2026-07-28 y el handshake de 2025 usando los mismos registros. npm run check:release verifica la compilación y las pruebas locales, incluido el paquete instalado contra un stub de API. La validación de API en vivo es separada; las pruebas omitidas no cuentan como éxito. El fijado de paquetes no garantiza disponibilidad o compatibilidad futura del upstream.

Licencia MIT — Copyright Dayan Decamp.