Mistral MCP server for document extraction
Turn text or Markdown invoices into typed JSON through MCP. mistral-mcp
uses Mistral chat to extract vendors, totals, line items and due dates, then
validates the response schema. Optional Mistral OCR handles PDF and image inputs.
process_document also supports contracts, identity documents and automatic
classification. Six tools are available by default, including chat, vision,
transcription and code completion.
Français · Migration guide · Examples · Deployment
npm package · 1.0.0 release notes · GitHub releases · Mistral API docs
Version 1.0.0 — breaking changes from 0.11.0: core now exposes six tools;
existing orchestration clients must choose an explicit profile. Document results
require extraction_source, and ocr_confidence / page_count can be null.
Migration and rollback instructions.
Install in an MCP client
Requires Node.js 20+, npm and a Mistral API key with access and quota for the
requested model. For clients using mcpServers JSON, configure the stdio server:
{
"mcpServers": {
"mistral": {
"command": "npx",
"args": ["-y", "[email protected]"],
"env": {
"MISTRAL_API_KEY": "your_key_here",
"MISTRAL_DEFAULT_MODEL": "ministral-3b-latest",
"MISTRAL_MCP_PROFILE": "core"
}
}
}
}
This runs npx -y [email protected]. Restart the client and refresh its tool
catalog. The server reads the environment supplied by the client; it does not
load .env automatically. Use your client's secret configuration for the key.
ministral-3b-latest was verified on the test account; model access and free
quota depend on your account. Check your limits
before making calls. Local MCP hosting still sends extraction requests to Mistral.
Quick start: an existing text or Markdown invoice
The invoice script and fixtures are source examples, not included in the npm package. Check out the release tag and build from the repository root:
git clone https://github.com/Swih/mistral-mcp.git
cd mistral-mcp
git checkout v1.0.0
npm ci
npm run build
Set the key and chat model in your environment or in a local .env file:
MISTRAL_API_KEY=your_key_here
MISTRAL_DEFAULT_MODEL=ministral-3b-latest
The example loads .env with dotenv. Keep the key out of version control.
Choose a chat model with quota on your account; the default may have zero quota.
npm run example:invoice -- test/fixtures/invoice-text.md --output invoice-result.json
This uses the synthetic Markdown invoice.
For your own existing UTF-8 .txt or .md invoice, the command syntax is:
node examples/invoice.mjs <local-file.txt|local-file.md> [--output result.json]
The script reads the text locally and calls process_document with
source: { type: "text", text: "..." }, kind: "invoice" and
options.cache: "bypass" through the local server's core profile. The text must
contain non-whitespace content and fit within 60,000 UTF-16 code units (JavaScript
string length). Markdown and whitespace are preserved unchanged. There is no
Files upload or OCR call; invoice extraction sends the text to Mistral chat.
The example uses Mistral Cloud only and still requires a key and chat quota;
processing is not entirely local or guaranteed free. Check your account's
limits.
Without --output, it prints validated JSON; with it, it writes to a new file and
prints that path. Existing files are not overwritten. The output path is reserved
before API calls and may remain empty after failure; remove it or choose a new
path before retrying.
On 2026-09-28, the live text test and the CLI
example succeeded with ministral-3b-latest, using chat only. The verified fields
were vendor ACME SAS, total 12960 EUR, due date 2026-09-11 and the quantities,
unit prices and amounts of all three invoice lines. This verifies one synthetic
invoice, not a general accuracy or reliability score.
For a PDF or image, the existing OCR route remains available:
npm run example:invoice -- test/fixtures/corpus/invoice-fr-table.pdf --output invoice-ocr-result.json
PDF, PNG, JPEG and WebP files up to 20 MiB require Files, OCR and chat access and
quota. The script uploads the file, calls process_document and attempts to
delete the upload in finally, including after extraction failure. There is no
separate OCR readiness probe. Upload and cleanup use the Files API without
exposing admin tools in core. Known limitation: the test account's HTTP 429
/ zero OCR quota blocked live OCR validation. The successful text run does not
validate OCR extraction.
Compare any extracted result against its source. The synthetic PDF and fixture ground truth describe expected document content, not captured live output. Schema validation checks the shape and types of the response; it does not verify factual accuracy, invoice arithmetic, tax treatment or accounting correctness. Review extracted fields against the source before using them.
Profiles
MISTRAL_MCP_PROFILE selects one of five profiles. The default is core for
Mistral Cloud; a custom MISTRAL_BASE_URL infers self-hosted unless you set a
profile explicitly.
full remains a deprecated alias of admin, not a sixth profile. Set
MISTRAL_MCP_PROFILE=metier-docs to preserve the old core tool set after upgrading;
choose workflows for orchestration alone or admin for the complete tool set.
Restart the server and refresh tool discovery after changing profiles.
npx -y [email protected] --doctor reports the local profile and tool list without API
calls. The mistral://capabilities resource reports the active endpoint, tool
families and reasons for omitted tools. Neither proves account access or quota.
Core tools and document behavior
process_document accepts source: { type: "text", text: string }, a document
URL, a base64 image or an uploaded file ID. Text may contain Markdown and is
preserved unchanged; blank or whitespace-only strings and strings above 60,000
UTF-16 code units are rejected for every kind, including generic.
kind is auto (default), invoice, contract, id_document or generic.
Successful calls return readable content and JSON structuredContent; failures
return isError: true.
For example, these are tool arguments using synthetic input, not a live result:
{
"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" }
}
On a cache miss or with cache: "bypass", auto calls chat to classify even a
text source; invoice, contract and id_document use chat for typed extraction.
Explicit kind: "generic" with a text source makes no API calls and returns
the supplied text as both ocr_text and structured_text.
Every successful result includes these fields:
options.maxPagesandoptions.minOcrConfidenceapply only to OCR sources. They do not paginate or score supplied text. For OCR, missing, incomplete or invalid confidence scores cause an error, as do scores below the requested minimum. The default0.3is unmeasured; OCR confidence does not establish extraction accuracy.- For OCR sources,
options.maxPagesdefaults to 50 (maximum 200). Typed extraction rejects OCR text above 60,000 UTF-16 code units: split the document or usegenericfor OCR text. The text-source input limit still applies togeneric.options.languageHintsguides typed extraction, not the OCR model. options.cache: "bypass"skips cache reads and writes. Other modes areread_onlyandread_write. Identity documents bypass the cache by default, including afterautoclassification; explicitread_writeopts them in.- Cache files contain extracted content.
MISTRAL_MCP_CACHE_DIRsets the location;MISTRAL_MCP_CACHE_TTL_HOURSdefaults to 168 hours (0disables reuse and new writes). Cleanup is opportunistic during cache operations. Bypass does not erase older entries, and expiration does not guarantee deletion at a set time. Pipeline versionv1.0.0-text.1invalidates reuse of older cache entries; it does not guarantee their immediate deletion.
The synthetic corpus separates required OCR text
from expected extracted invoice fields. npm run eval:docs evaluates these
separately through real API calls. Fixture truth is not a live accuracy result;
text-based synthetic PDFs do not establish accuracy on degraded scans.
Development and evaluation guidance.
API and deployment references
mistral://capabilities describes the active tool set. mistral://models reads the
upstream catalog and reports fallback if the API call fails. mistral://voices
is available in admin; mistral://workflows is available in metier-docs,
workflows and admin. Catalog presence does not establish access or quota.
You can host the MCP process and configure its upstream endpoint, credentials, tool exposure and cache policy. By default, requests go to Mistral Cloud: local MCP hosting does not make document inference local. These controls alone do not establish data residency or regulatory compliance.
A custom MISTRAL_BASE_URL infers self-hosted: chat, streaming chat, embeddings,
function calling and vision, subject to endpoint/model support. It does not
include OCR or process_document. An explicit profile overrides inference but
does not add missing APIs to a backend.
stdio is the default transport. --http or MCP_TRANSPORT=http enables
Streamable HTTP at 127.0.0.1:3333/mcp by default, with configurable bearer
authentication and allowed origins. Integrated OAuth is not provided.
Tool audit records go to stderr and omit arguments and result payloads;
MISTRAL_MCP_AUDIT=off disables them.
The protocol-era tests cover MCP 2026-07-28
and the 2025 handshake using the same registrations. npm run check:release
checks the build and local tests, including the installed package against an API
stub. Live API validation is separate; skipped tests do not count as success.
Package pinning does not guarantee future upstream availability or compatibility.
MIT license — Copyright Dayan Decamp.
