Mistral MCP — Document Extraction
This server lets you use Mistral AI to chat, code, analyze images, OCR documents, transcribe audio, extract structured document data, and run Mistral workflows.
Chat: Generate completions with Mistral models, including structured JSON/schema output and token usage.
Code: Use Codestral fill-in-the-middle completions for editor autocomplete or refactoring.
Vision: Chat with images or document URLs using vision-capable Mistral models.
OCR: Convert PDFs/images to markdown with tables, annotations, confidence scores, headers/footers, and bounding boxes.
Audio: Transcribe speech with Voxtral, with optional diarization, timestamps, context bias, and language hints.
Document extraction: With the core profile,
process_documentturns text/Markdown or OCR into schema-validated JSON for invoices, contracts, ID documents, or generic text, with classification and cache controls.Workflows: Execute, monitor, and signal/query/update running Mistral workflow executions.
Profiles: Expose different tool sets (
core,metier-docs,workflows,admin,self-hosted), including admin tools for Files, Batch, Conversations, and Libraries.
Enables durable workflow execution with Temporal, supporting starting, querying, and signaling long-running Mistral Workflows, including human-in-the-loop checkpoints.
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", "mistral-mcp@1.0.0"],
"env": {
"MISTRAL_API_KEY": "your_key_here",
"MISTRAL_DEFAULT_MODEL": "ministral-3b-latest",
"MISTRAL_MCP_PROFILE": "core"
}
}
}
}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.
Related MCP server: MCP Server TypeScript
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 buildSet 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-latestThe 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.jsonThis 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.jsonPDF, 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.
Profile | Tools | Scope in |
| 6 | Documents, chat, vision, transcription and code completion |
| 17 | Preserved legacy profile: the six core tools plus all 11 orchestration tools; a superset of the old 16-tool core |
| 11 | Workflows, connectors and search-index discovery |
| 46 | All tools implemented by this server, including Files, Batch, Conversations and Libraries |
| 5 | Chat, streaming chat, embeddings, function calling and vision on a compatible endpoint |
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 mistral-mcp@1.0.0 --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
Tool | Purpose |
| Supplied text/Markdown or OCR, optional classification and schema-validated extraction for invoices, contracts, identity documents or generic text |
| Raw OCR text, tables, annotations and optional blocks from PDFs or images |
| Chat with images supplied by URL or base64 |
| Chat completion, including structured response formats |
| Audio transcription with optional speaker diarization |
| Fill-in-the-middle code completion |
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:
Field | Provided text / Markdown | Successful OCR source |
|
|
|
| Original input text, unchanged | OCR text |
|
| Number from 0 to 1 |
|
| Number of processed pages |
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.
Reference | Contents |
Removed core tools, explicit profiles, pinned | |
Local invoices, transcription and library-backed conversations | |
Tool families and MCP tool input schemas | Complete tool membership and argument reference |
Meeting minutes, email replies, commits, legal summaries, invoice reminders and code review | |
Docker, Compose, Kubernetes, custom endpoints, cache and HTTP settings | |
HTTPS deployment; public connector calls are not established as end-to-end validated here | |
Optional plugin with 11 skills, pinned to | |
Build, tests, evaluation and release checks | |
Changes and security reporting |
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.
Available Tools
6 toolscodestral_fimCodestral fill-in-the-middle completionARead-only
Fill-in-the-middle code completion with Codestral.
Given prompt (code preceding the cursor) and suffix (code after the cursor),
Codestral writes the middle. Use for editor autocomplete scenarios, code-patching
agents, or structured refactors where you know the target boundaries.
Default stop tokens: [] — let the model decide. Override with stop if needed.
Inputs: prompt (required), suffix (required), seed, stop, +4 more. Returns: text, model, usage, finish_reason
mistral_chatMistral chat completionARead-only
Generate a chat completion using a Mistral model.
When to use:
Drafting French (or any European-language) content where Mistral shines.
Codestral for code-specific generation/review.
Ministral for cheap / low-latency classification.
Returns structured content with the assistant text and token usage. Does NOT stream — use mistral_chat_stream for long outputs with progress updates.
Inputs: messages (required), seed, model, top_p, +4 more. Returns: text, model, usage, finish_reason, +1 more
mistral_ocrMistral OCR (document to markdown)ARead-onlyIdempotent
Run Mistral OCR on a PDF or image, returning structured markdown per page.
Input document is one of:
{ type: "document_url", documentUrl: "https://...pdf" }
{ type: "image_url", imageUrl: "https://..." | "data:image/..." }
{ type: "file", fileId: "" }
Options:
pages: array of 0-indexed page numbers or string like "0-5,7".tableFormat: 'markdown' (default) or 'html'.extractHeader/extractFooter: include page header/footer when present.includeImageBase64: embed extracted image bytes as base64 in the response.document_annotation_format: JSON schema for whole-document structured extraction.bbox_annotation_format: JSON schema for extracted image / bbox annotations.confidence_scores_granularity: 'page', 'word', or 'block'. 'block' adds per-block content/type confidence underpages[].blocks[].confidence_scoresand requires OCR 4.1 or newer.includeBlocks: return paragraph-level blocks (bounding box + type) in reading order — titles, lists, tables, images, equations, captions, code, references, aside text, header, footer, signature. Requires OCR 4 (mistral-ocr-4-0) or newer; older models accept the flag but return an emptyblocksarray.
Returns pages[].markdown plus optional pages[].hyperlinks, header, footer,
images bounding boxes, blocks, annotations, confidence scores, and dimensions.
Inputs: document (required), model, pages, imageLimit, +10 more. Returns: model, pages, usage, annotations, +2 more
mistral_visionMistral multimodal chat (vision)ARead-only
Chat completion with multimodal input: text + image_url parts.
Requires a vision-capable model. Accepted:
pixtral-large-latest
pixtral-12b-latest
mistral-large-latest
mistral-medium-latest
mistral-small-latest
Each message's content is either a plain string (pure text) or an array of
parts { type: 'text', text } / { type: 'image_url', imageUrl }. The image URL
can be an https URL or a data: URI base64 payload.
Returns the assistant text + token usage. For non-visual requests, prefer mistral_chat.
Inputs: messages (required), seed, model, top_p, +2 more. Returns: text, model, usage, finish_reason
process_documentProcess a business document end-to-endARead-onlyIdempotent
Single-call pipeline: provided text/Markdown or Mistral OCR → classify (if kind=auto) → typed extraction → validation. source.type=text skips OCR and Files uploads. Text with kind=generic makes no API calls; classification and typed extraction use Mistral chat. Results expose extraction_source. Provided text has null ocr_confidence and page_count; ocr_text contains the supplied text unchanged. Replaces the manual chain of mistral_ocr + mistral_chat + JSON parsing.
Kinds: contract | invoice | id_document | generic. Use kind=auto to let the server classify.
Returns a discriminated union — switch on kind to access typed fields.
Validation checks schema and, for OCR sources, OCR confidence; not factual or accounting accuracy.
Typed extraction rejects text longer than 60000 characters rather than truncating it.
Cache keys include source, kind, page limit, endpoint, models and pipeline version. Override location with MISTRAL_MCP_CACHE_DIR. Override mode with options.cache. Default cache mode is 'read_write' EXCEPT for kind=id_document (auto-bypass to avoid persisting PII). Set options.cache='read_write' explicitly to opt in for id documents.
options.maxPages and options.minOcrConfidence apply only to OCR sources. The confidence floor defaults to 0.3. Below the floor the
tool returns isError. Missing or partial confidence scores also return isError;
use mistral_ocr directly if you need raw OCR without a confidence guarantee.
0.3 is a conservative starting point, not a measured one: calibrate it for your
corpus with npm run eval:docs.
Inputs: source (required), kind, options. Returns: dob, kind, name, total, +22 more
voxtral_transcribeVoxtral speech-to-textARead-onlyIdempotent
Transcribe an audio file to text using Mistral Voxtral.
Accepted models:
voxtral-mini-latest
voxtral-small-latest
Audio source is one of:
{ type: "file_url", fileUrl: "https://..." } (public URL)
{ type: "file", fileId: "" }
Options:
language: ISO-639-1 hint (e.g. 'fr', 'en'). Boosts accuracy when known.temperature: sampling temperature.diarize: return per-speaker segments (default false).timestampGranularities: ['segment'] to return per-segment timestamps.contextBias: list of phrases/terms that should bias the decoder.
Returns plain text, detected language, optional segments[], and token usage.
Inputs: audio (required), model, diarize, language, +3 more. Returns: text, model, usage, language, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct modality/action: code FIM, text chat, OCR, vision chat, document pipeline, and audio transcription. There is minor overlap between mistral_chat and mistral_vision (both chat) and between process_document and mistral_ocr, but the descriptions explicitly steer selection, so confusion is limited.
Names mix provider-prefixed conventions (codestral_fim, mistral_chat, mistral_ocr, mistral_vision, voxtral_transcribe) with a plain action name (process_document). The pattern is somewhat readable but not a predictable verb_noun scheme and the provider prefixes fragment consistency.
Six tools is well-scoped for a multimodal Mistral wrapper, with each tool covering a distinct capability rather than redundancy. Slightly broad for a server named 'Document Extraction' since it also includes code completion and chat, but not excessive.
Covers OCR, vision, chat, transcription, and a combined pipeline, but several tools reference a Files API (fileId) that is not exposed as a tool, creating a dead-end for uploading files. No model-listing or file-management operations leave workflows partially blocked.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server for progressive tool usage at any scale (see https://klavis.ai)
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Related MCP Servers
- -licenseNot gradedqualityDmaintenanceA TypeScript implementation of a Model Context Protocol server and client that enables interaction with language models (specifically Mistral running on Ollama).-
- -licenseNot gradedqualityNot gradedmaintenanceA production-ready TypeScript MCP server providing basic tools (add, echo, timestamp), resources (server info, greetings, data access), and prompt templates (analyze, code-review, summarize). Serves as a foundation for building custom MCP servers with extensible architecture.547 npm-
- AlicenseBqualityDmaintenanceA TypeScript-based MCP server that provides tools to interact with local Codex and Gemini CLIs via stdio transport. It enables users to execute prompts through the ask_codex and ask_gemini tools, supporting custom models and timeout configurations.111 npm6MIT
- FlicenseAqualityDmaintenanceA TypeScript MCP server template with Zod validation, dual transport (stdio/HTTP), and modular architecture for building MCP-compatible tools, resources, and prompts.11-