Swih/mistral-mcp

**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:
This runs npx -y mistral-mcp@1.0.0. 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:
Set the key and chat model in your environment or in a local .env file:
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.
This uses the synthetic Markdown invoice.
For your own existing UTF-8 .txt or .md invoice, the command syntax is:
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:
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