{
  "markdown": "# mistral-mcp\n\n> **Mistral, wherever you run it.**\n> MCP server for the full Mistral AI API — chat, OCR, audio (Voxtral), code (Codestral), vision, agents, batch, durable workflows — against Mistral Cloud or your own infrastructure.\n> Plug into Claude Code, Cursor, Zed, Windsurf, or Claude Desktop in one command.\n>\n> _Version française : [README.fr.md](./README.fr.md)_\n\n[![npm version](https://img.shields.io/npm/v/mistral-mcp?color=brightgreen)](https://www.npmjs.com/package/mistral-mcp)\n[![CI](https://github.com/Swih/mistral-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Swih/mistral-mcp/actions/workflows/ci.yml)\n[![Glama MCP score](https://glama.ai/mcp/servers/Swih/mistral-mcp/badges/score.svg)](https://glama.ai/mcp/servers/Swih/mistral-mcp)\n[![license](https://img.shields.io/badge/license-MIT-black)](./LICENSE)\n![MCP spec](https://img.shields.io/badge/MCP%20spec-2026--07--28-purple)\n\n---\n\n## What this is\n\n`mistral-mcp` exposes the full Mistral AI API as a set of MCP tools, resources, and prompts. An MCP client (Claude Code, Cursor, etc.) can call `mistral_ocr` to extract text from a PDF, `voxtral_transcribe` to transcribe a meeting recording, or `workflow_execute` to start a durable multi-step process — all without leaving the agent loop.\n\n**Unique to Mistral and not available from other MCP servers:**\n- `mistral_ocr` — Mistral Document AI: structured text + bbox annotations from any PDF or image\n- `voxtral_transcribe` — Voxtral: transcription with optional speaker diarization\n- `codestral_fim` — Codestral fill-in-the-middle (FIM) for inline code completion\n- `workflow_*` (6 tools) — Temporal-backed durable execution: what is deployed and runnable, what is running, human-in-the-loop signals, and graceful or forced stop\n- French-optimized models (`mistral-large-latest`, `mistral-medium-latest`) and curated French prompts\n\n**What this server does not expose:** fine-tuning, user management, non-FR/EN prompts.\n\n---\n\n## Why this matters for European teams\n\n`mistral-mcp` is designed for teams that want to use Mistral capabilities inside MCP clients (Claude Code, Cursor, Zed, Windsurf, Claude Desktop) while keeping control over deployment, API keys, cache behavior, and tool exposure.\n\nThis can be useful for European organisations evaluating AI stacks under GDPR, DORA, sector-specific constraints (HDS, EBA), or internal sovereignty requirements.\n\n**What this project provides:**\n\n- self-hosted MCP server, no mandatory SaaS proxy\n- bring-your-own Mistral API key (BYOK) — Mistral states API data is not used to train its models\n- `MISTRAL_BASE_URL` routes every call to your own OpenAI-compatible endpoint (vLLM, TGI, LiteLLM, an internal gateway) — no traffic to `api.mistral.ai`\n- lean `core` profile and focused `metier-docs` profile to limit tool exposure\n- `process_document` cache configurable per-call and via `MISTRAL_MCP_CACHE_DIR`, with a retention window (`MISTRAL_MCP_CACHE_TTL_HOURS`, default 7 days, `0` to disable) after which entries are deleted, not merely bypassed\n- ID document cache bypass enabled by default, even when `kind:\"auto\"` resolves to `id_document`\n- Streamable HTTP + bearer auth path for controlled / on-prem deployments\n- French-first prompts and skills (meeting minutes, legal summary, invoice reminder, commit message, email reply)\n- free Experiment tier on the Mistral side covers most evaluation needs (~1B tokens/month)\n\n**What this project does NOT claim:**\n\n- it is not a GDPR, DORA, HDS, or ISO certification, and it does not replace a DPIA, vendor review, security audit, or legal assessment\n- Mistral provider terms, data residency, subprocessor list, retention settings, and incident handling must be reviewed separately at [mistral.ai/terms](https://mistral.ai/terms) and [legal.mistral.ai](https://legal.mistral.ai)\n- this repo is community-maintained, not an official Mistral integration; nothing here modifies Mistral's contractual data terms with you\n\nIn practice, `mistral-mcp` reduces the integration surface you have to assess. It does not replace the legal/compliance work itself.\n\n---\n\n## Quick start\n\n**Claude Code** (recommended — auto-installs, prompts for API key, ships 11 skills):\n```text\n/plugin install mistral-mcp@swih-plugins\n```\n\n**Cursor / Zed / Windsurf / Claude Desktop** — add to your MCP settings JSON:\n```json\n{\n  \"mcpServers\": {\n    \"mistral\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mistral-mcp@latest\"],\n      \"env\": { \"MISTRAL_API_KEY\": \"your_key_here\" }\n    }\n  }\n}\n```\n\n**Manual Claude Code registration:**\n```bash\nclaude mcp add mistral -- npx -y mistral-mcp@latest\n```\n\n---\n\n## Profiles\n\n`MISTRAL_MCP_PROFILE` controls how many tools are exposed (default: `core`).\n\n| Profile | Tools | Use when |\n|---|---|---|\n| `core` (default) | 13 | Daily agentic use — lean context footprint |\n| `admin` | 41 | Full Mistral API surface — embeddings, streaming, batch, classify, files, agents, TTS, document extraction, stateful conversations, RAG libraries. Best for debug, CI, scripts. |\n| `workflows` | 8 | Pipeline orchestration + connectors only |\n| `metier-docs` | 14 | Documents vertical — core + `process_document` macro-tool |\n| `self-hosted` | 5 | Inference on your own OpenAI-compatible endpoint — inferred from `MISTRAL_BASE_URL` |\n\n> `full` is accepted as a deprecated alias of `admin` for backward compatibility.\n\n```bash\nMISTRAL_MCP_PROFILE=admin npx mistral-mcp\n```\n\nRead `mistral://capabilities` from any client to see which tool families are on,\nwhich are off, and why — no need to diff this table against your deployment.\n\n---\n\n## Tools\n\n### Core profile (16 tools — always available)\n\n| Tool | What it does |\n|---|---|\n| `mistral_chat` | Chat completion. Supports all Mistral models, `response_format`, `reasoning_effort` for Magistral. |\n| `mistral_vision` | Multimodal chat with images (URL or base64). |\n| `mistral_ocr` | Document AI — extract text, bbox, and JSON annotations from PDFs/images. Pass `includeBlocks: true` for OCR 4 paragraph-level blocks (text/title/table/image/equation/... with bounding boxes). |\n| `codestral_fim` | Fill-in-the-middle code completion (Codestral model). |\n| `voxtral_transcribe` | Audio → text. Pass `diarize: true` for speaker separation. |\n| `workflow_execute` | Start a Mistral Workflow (Temporal-backed durable execution). |\n| `workflow_status` | Poll a running workflow — returns `RUNNING \\| COMPLETED \\| FAILED \\| ...`. |\n| `workflow_interact` | Signal / query a running workflow. Used for human-in-the-loop checkpoints. |\n| `workflow_deployments_list` | List workflow deployments and whether each has a live worker. Call it before `workflow_execute` — a listed workflow with no active deployment answers 404. |\n| `workflow_runs_list` | List workflow executions, filtered by workflow, status or deployment. |\n| `workflow_stop` | Stop an execution — `cancel` (graceful, runs cleanup handlers) or `terminate` (immediate). |\n| `connectors_list` | Discover Mistral Connectors (MCP/HTTP integrations) visible to the caller. |\n| `connectors_get` | Fetch one connector's public metadata (never credentials). |\n| `connectors_list_tools` | List the MCP tools a connector exposes, with their input schema. |\n| `connectors_call_tool` | Invoke a connector's tool — real MCP `CallToolResult` passthrough. |\n| `rag_indexes_list` | List the search-index deployments on your account, with backend and document counts. |\n\n### Documents vertical (`MISTRAL_MCP_PROFILE=metier-docs`)\n\n| Tool | What it does |\n|---|---|\n| `process_document` | Single-call macro-tool: OCR → classify (kind=auto) → typed extraction → validation → cache. Kinds: `contract` / `invoice` / `id_document` / `generic`. Returns a discriminated union. PII-safe cache (id_document auto-bypass). Configurable `minOcrConfidence`. |\n\n### Admin profile only (+28 tools, set `MISTRAL_MCP_PROFILE=admin`)\n\n| Group | Tools |\n|---|---|\n| Generation | `mistral_chat_stream`, `mistral_embed`, `mistral_tool_call` |\n| Agents | `mistral_agent`, `mistral_moderate`, `mistral_classify` |\n| Audio | `voxtral_speak` (TTS) |\n| Files | `files_upload`, `files_list`, `files_get`, `files_delete`, `files_signed_url` |\n| Batch | `batch_create`, `batch_get`, `batch_list`, `batch_cancel` |\n| Conversations | `conversation_start`, `conversation_append`, `conversation_get`, `conversation_list`, `conversation_history`, `conversation_delete` — stateful multi-turn agent loops with Mistral's built-in tools (web_search, code_interpreter, image_generation, document_library) |\n| Libraries (RAG) | `libraries_list`, `libraries_get`, `libraries_documents_list`, `libraries_documents_upload`, `libraries_documents_status` — discover and feed already-created Mistral Libraries; pair with `conversation_start`'s `documentLibraryIds` to search them |\n\n---\n\n## Resources\n\n| URI | What it returns |\n|---|---|\n| `mistral://capabilities` | Which tool families are registered, which are not, and why — plus the active profile and endpoint |\n| `mistral://models` | Live model catalog, read from the endpoint actually in use |\n| `mistral://voices` | Live Voxtral TTS voice catalog — registered only when the `tts` family is on (`admin`) |\n| `mistral://workflows` | Live list of deployed workflows (use `name` as `workflowIdentifier`) — not registered under `self-hosted` |\n\n---\n\n## Prompts\n\nCurated prompts with structured arguments and MCP completion support:\n\n| Prompt | Input | Output |\n|---|---|---|\n| `french_meeting_minutes` | transcript text | Structured French meeting minutes |\n| `french_email_reply` | received email + context | Polished French reply |\n| `french_commit_message` | git diff | Conventional Commits message in French |\n| `french_legal_summary` | legal document text | Plain-French summary + key clauses |\n| `french_invoice_reminder` | debtor, amount, days overdue, tone | B2B dunning letter in French |\n| `codestral_review` | git diff | Focused code review (security / logic / style) |\n\n---\n\n## Claude Code skills (11)\n\nInstall via the `swih-plugins` marketplace to get these namespaced skills:\n\n**Routing**\n- `/mistral-mcp:mistral-router` — picks the right Mistral model + tool for any task\n\n**Code**\n- `/mistral-mcp:codestral-review` — fetches the current diff, runs a focused review\n\n**French workflows**\n- `/mistral-mcp:french-commit-message` — Conventional Commits message in French\n- `/mistral-mcp:french-meeting-minutes` — audio or text → structured French minutes\n- `/mistral-mcp:french-invoice-reminder` — B2B dunning letter with controlled tone\n\n**Document & audio processing**\n- `/mistral-mcp:contract-analyzer` — OCR → risk-rated clause extraction (JSON)\n- `/mistral-mcp:pdf-invoice-extractor` — OCR → structured invoice fields for reconciliation\n- `/mistral-mcp:audio-dispatch` — transcribe + diarize → per-speaker action plan\n\n**Human-in-the-loop workflows**\n- `/mistral-mcp:contract-review-workflow` — durable contract review with approval gates\n- `/mistral-mcp:compliance-audit-workflow` — multi-step audit with mid-run findings + decisions\n- `/mistral-mcp:research-pipeline-workflow` — hypothesis-driven research with amendment injection\n\n---\n\n## Install\n\n```bash\n# Run directly (no global install)\nnpx mistral-mcp\n\n# Global install\nnpm install -g mistral-mcp && mistral-mcp\n\n# Docker\ndocker build -t mistral-mcp .\ndocker run -i --rm -e MISTRAL_API_KEY=your_key mistral-mcp\n\n# From source\ngit clone https://github.com/Swih/mistral-mcp.git\ncd mistral-mcp && npm install && npm run build\nnode dist/index.js\n```\n\n---\n\n## Document ingestion, evaluated\n\n`process_document` ships with a corpus and a harness, because \"handles\nheterogeneous PDFs\" is a claim, and a claim without a measurement is marketing.\n\n```bash\nnpm run fixtures:generate   # rebuild the corpus from source (no key needed)\nnpm run eval:docs           # score it against real OCR (needs MISTRAL_API_KEY)\n```\n\nThe corpus is eight synthetic documents chosen for the cases that actually\nbreak ingestion pipelines, not for the ones that flatter them: a rotated\nlandscape scan (`/Rotate 90`), ruled line-item tables, side-by-side address\ncolumns, a blank page in the middle of a document, mixed FR/EN, French accents\nand the euro sign, and one near-empty page. Ground truth for each document —\nexpected kind, page count, and the strings that must survive OCR — lives in\n`test/fixtures/corpus.json`.\n\nEverything in it is invented: fictional companies, fictional people, fictional\nidentifiers. **No real PII is in this repo, and none should be added** — the\ncorpus is only useful if it can be published.\n\n`npm run eval:docs` reports, per document, whether `kind: \"auto\"` classified it\ncorrectly, whether the required fields survived, and the OCR confidence. It\nthen derives a `minOcrConfidence` from the run: the midpoint between the worst\ndocument that extracted cleanly and the best document marked low-signal. When\nthose two overlap, it says no threshold is defensible rather than inventing\none.\n\nThe shipped default of `0.3` is a conservative starting point, **not** a\nmeasured value. Run the harness on your own documents and set the number that\nrun justifies.\n\n---\n\n## Observability\n\nEvery tool call emits one JSON line on stderr, and the caller's W3C trace\ncontext follows the request all the way to the inference endpoint.\n\n```json\n{\"ts\":\"2026-08-28T09:14:02.117Z\",\"kind\":\"tool_call\",\"tool\":\"mistral_ocr\",\"outcome\":\"ok\",\"duration_ms\":1840,\"trace_id\":\"4bf92f3577b34da6a3ce929d0e0e4736\",\"span_id\":\"00f067aa0ba902b7\"}\n```\n\n- **Trace continuity.** `traceparent`, `tracestate` and `baggage` arrive in the\n  MCP request's `_meta` and are stamped onto the outgoing HTTP call, so your\n  collector joins the MCP span to the Mistral (or vLLM) span it caused instead\n  of showing two unrelated traces. A malformed header is ignored, never fatal.\n- **No payloads, ever.** A line says what ran, how long it took and whether it\n  failed. Prompts, documents, transcripts, arguments and model output never\n  appear — those are your records, and this process has no business copying\n  them into a log it does not own. `test/stdio/observability.test.ts` asserts\n  that negative directly against the built binary.\n- **Nothing to enable, and one thing to disable.** It is on by default because\n  an audit trail you have to discover is one you will not have when you need\n  it. `MISTRAL_MCP_AUDIT=off` silences it. stderr is used because stdout\n  carries JSON-RPC, and because MCP's own `logging` capability is deprecated\n  in 2026-07-28 in favour of stderr and OpenTelemetry.\n\nThe instrumentation wraps `registerTool` rather than each handler, so a tool\ncannot be left out of the trail without being left out of the server.\n\n---\n\n## Self-hosted inference\n\nPoint `MISTRAL_BASE_URL` at any OpenAI-compatible endpoint — vLLM, TGI, LiteLLM,\nan internal token factory — and every request goes there instead of\n`api.mistral.ai`:\n\n```bash\nMISTRAL_BASE_URL=http://vllm.internal:8000/v1 MISTRAL_DEFAULT_MODEL=my-org/mistral-small-3.2 npx mistral-mcp\n```\n\nTwo things change when the endpoint is not Mistral's:\n\n1. **The profile becomes `self-hosted`.** Only the five tools such an endpoint\n   can actually serve stay registered — `mistral_chat`, `mistral_chat_stream`,\n   `mistral_embed`, `mistral_tool_call`, `mistral_vision`. OCR, Voxtral, Files,\n   Batch and Workflows are Mistral-platform endpoints; advertising them against\n   vLLM would only produce 404s the calling model has to guess its way out of.\n   Set `MISTRAL_MCP_PROFILE` explicitly if your gateway does proxy the full API.\n2. **Model ids are no longer checked against a list.** Any non-empty string is\n   forwarded as-is, because your endpoint's identifiers are yours.\n\n`mistral://capabilities` reports the active endpoint, the profile, whether it was\ninferred, and the reason each unavailable family is off.\n\nCompose and Kubernetes manifests, plus the full environment reference, are in\n[`deploy/README.md`](./deploy/README.md).\n\n---\n\n## Protocol\n\nThe server speaks **MCP 2026-07-28** and the 2025-era handshake, from the same\ntool registrations, on the same endpoint. That matters because practically\nevery client shipping today still opens with the 2025 handshake: upgrading the\nserver does not ask anyone to upgrade their client.\n\n| | 2025-era client | 2026-07-28 client |\n|---|---|---|\n| Handshake | `initialize` | `server/discover` |\n| Tools, resources, prompts | identical set | identical set |\n| `structuredContent` + `outputSchema` | yes | yes |\n| Cache hints (`ttlMs`/`cacheScope`) | not in the revision | yes |\n\n`test/stdio/protocol-eras.test.ts` drives the built binary with a real 1.30.x\nclient and a real 2026-07-28 client and asserts both see the same tools — the\ncompatibility claim above is a test, not a promise.\n\nBuilt on `@modelcontextprotocol/server` 2.x. Sampling and elicitation tools are\nnot exposed: sampling is deprecated in 2026-07-28, and the multi-round-trip\nreplacement is a client capability this server has no use for.\n\n---\n\n## Transport\n\n| Mode | How to enable | Default |\n|---|---|---|\n| **stdio** | Default | `node dist/index.js` |\n| **Streamable HTTP** | `MCP_TRANSPORT=http` or `--http` flag | `127.0.0.1:3333/mcp` |\n\nHTTP env vars: `MCP_HTTP_HOST`, `MCP_HTTP_PORT`, `MCP_HTTP_PATH`, `MCP_HTTP_TOKEN` (bearer auth), `MCP_HTTP_ALLOWED_ORIGINS`.\n\nHTTP serving is stateless per request in both protocol eras, so `MCP_HTTP_STATELESS` no longer does anything and was removed in 0.10.0. Setting it is harmless.\n\n`/healthz` is public and does not touch the MCP server.\n\n---\n\n## Use as a Mistral Connector (beta)\n\n`mistral-mcp` ships the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2026-07-28/) and bearer auth that [Mistral Connectors](https://docs.mistral.ai/agents/tools/mcp) require. Deployment guides for Cloudflare Tunnel, Fly.io, and Cloud Run are in [`deploy/connector-public.md`](./deploy/connector-public.md).\n\n| Surface | Status |\n|---|---|\n| Local MCP clients (Claude Code, Cursor, Zed, Windsurf, Claude Desktop) | Stable |\n| Streamable HTTP transport + bearer auth | Tested locally (handshake + 401 + initialize verified) |\n| Mistral Connector registration via `POST /v1/connectors` | **Setup guide provided — Connectors are a beta feature, the API may change** |\n| Connector tool calls in Conversations/Agents | Untested end-to-end (requires public HTTPS deployment) |\n| OAuth 2.1 Connector auth | Pending — bearer-only today |\n\n```bash\ncurl -X POST https://api.mistral.ai/v1/connectors \\\n  -H \"Authorization: Bearer $MISTRAL_API_KEY\" \\\n  -d '{\"name\":\"mistral_self\",\"server\":\"https://your-deploy/mcp\",\"visibility\":\"private\"}'\n```\n\n> Mistral Connectors expose **tools only** today. Resources and prompts remain available via local clients.\n\n---\n\n## Comparison with other Mistral MCP servers\n\n| Project | Scope | Best for |\n|---|---|---|\n| **mistral-mcp** | Full Mistral API + Workflows + 11 Claude Code skills | All-in-one self-hosted |\n| `mcp-mistral-ocr` (community) | OCR only | Lightweight OCR-only setup |\n| Speakeasy `mistral-mcp-server-example` | Generated demo | Reference / SDK template |\n| Composio `mistral_ai` toolkit | SaaS-routed Mistral tools | Hosted, no infra |\n\n`mistral-mcp` differentiates by combining OCR, Voxtral diarization, Codestral FIM, and Temporal-backed Workflows in one server, with French-first prompts and a Claude Code plugin marketplace.\n\n---\n\n## Development\n\n```bash\nnpm run dev      # tsx watch\nnpm run build    # tsc → dist/\nnpm run lint     # tsc --noEmit\nnpm test         # 190+ tests (unit + contract + stdio e2e + live API)\nnpm run inspector\n```\n\nTest pyramid: unit → contract → stdio e2e → live API (requires `MISTRAL_API_KEY`).\n\n---\n\n## License\n\nMIT — Copyright Dayan Decamp\n",
  "bytes": 19632,
  "sha": "34fceac49b1350021e709aff5c999ace95235b247bad3369329e5c9b979e56d8",
  "repo_slug": "swih/mistral-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_swih_mistral_mcp_mistral_mcp_bb5a6d77/readme"
}