https://github.com/Swih/mistral-mcp

Full Mistral AI MCP server — OCR, Voxtral audio, Codestral FIM, durable workflows, document extraction — for Claude Code, Cursor, Windsurf, Zed, Mistral Connectors
https://github.com/Swih/mistral-mcp

agent-skills agent-tools claude claude-code claude-desktop codestral cursor document-ai llm llm-tools mcp mcp-server mcp-servers mistral mistral-ai model-context-protocol ocr typescript voxstral zed

Last synced: 2 days ago
JSON representation

Full Mistral AI MCP server — OCR, Voxtral audio, Codestral FIM, durable workflows, document extraction — for Claude Code, Cursor, Windsurf, Zed, Mistral Connectors

Host: GitHub
URL: https://github.com/Swih/mistral-mcp
Owner: Swih
License: mit
Created: 2026-04-16T12:32:57.000Z (3 months ago)
Default Branch: main
Last Pushed: 2026-06-30T17:58:12.000Z (3 days ago)
Last Synced: 2026-06-30T19:26:23.775Z (3 days ago)
Topics: agent-skills, agent-tools, claude, claude-code, claude-desktop, codestral, cursor, document-ai, llm, llm-tools, mcp, mcp-server, mcp-servers, mistral, mistral-ai, model-context-protocol, ocr, typescript, voxstral, zed
Language: TypeScript
Homepage:
Size: 324 KB
Stars: 10
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.fr.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md

Awesome Lists containing this project

awesome-hermes-agent - beta - MCP server (stdio + Streamable HTTP) wrapping the full Mistral AI surface — chat, embeddings, vision, OCR, Voxtral audio (transcribe/speak), Codestral FIM, agents, moderation, classification, files, batch. 22 tools, 2 live resources, listed on the Official MCP Registry. Lets a Hermes user keep their primary reasoning model and route OCR / audio / FIM / classification to Mistral's specialized endpoints (free Experiment tier offers 1B tokens/month). (Integrations & Bridges / Deployment)
awesome-hermes-agent - beta

README

          # mistral-mcp

> **Serveur MCP pour Mistral AI — chat, OCR, audio (Voxtral), code (Codestral), vision, agents, batch et workflows durables.**

> Connectez-vous à Claude Code, Cursor, Zed, Windsurf ou Claude Desktop en une commande.

>

> _English version: [README.md](./README.md)_

[![npm version](https://img.shields.io/npm/v/mistral-mcp?color=brightgreen)](https://www.npmjs.com/package/mistral-mcp)

[![CI](https://github.com/Swih/mistral-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Swih/mistral-mcp/actions/workflows/ci.yml)

[![Glama MCP score](https://glama.ai/mcp/servers/Swih/mistral-mcp/badges/score.svg)](https://glama.ai/mcp/servers/Swih/mistral-mcp)

[![license](https://img.shields.io/badge/license-MIT-black)](./LICENSE)

![MCP spec](https://img.shields.io/badge/MCP%20spec-2025--11--25-purple)

---

## Ce que c'est

`mistral-mcp` expose l'API Mistral AI complète sous forme de tools, resources et prompts MCP. Un client MCP (Claude Code, Cursor, etc.) peut appeler `mistral_ocr` pour extraire le texte d'un PDF, `voxtral_transcribe` pour transcrire un enregistrement de réunion, ou `workflow_execute` pour démarrer un processus multi-étapes durable — sans quitter la boucle agent.

**Unique à Mistral, non disponible dans d'autres serveurs MCP :**

- `mistral_ocr` — Mistral Document AI : texte structuré + annotations bbox depuis n'importe quel PDF ou image

- `voxtral_transcribe` — Voxtral : transcription avec diarisation optionnelle par locuteur

- `codestral_fim` — Codestral fill-in-the-middle (FIM) pour la complétion de code inline

- `workflow_execute / status / interact` — exécution durable Temporal avec signaux humains-dans-la-boucle

- Modèles optimisés français (`mistral-large-latest`, `mistral-medium-latest`) et prompts curés en français

**Ce que ce serveur n'expose pas :** fine-tuning, gestion des utilisateurs, prompts hors FR/EN.

---

## Pourquoi c'est pertinent pour les équipes européennes

`mistral-mcp` est conçu pour les équipes qui veulent utiliser les capacités Mistral depuis des clients MCP (Claude Code, Cursor, Zed, Windsurf, Claude Desktop) tout en gardant la main sur le déploiement, les clés API, le comportement du cache et l'exposition des tools.

Cela peut être utile pour les organisations européennes qui évaluent une stack IA sous RGPD, DORA, contraintes sectorielles (HDS, EBA), ou exigences internes de souveraineté.

**Ce que ce projet apporte :**

- serveur MCP auto-hébergeable, pas de proxy SaaS obligatoire

- bring-your-own Mistral API key (BYOK) — Mistral déclare ne pas utiliser les données API pour entraîner ses modèles

- profil `core` léger et profil `metier-docs` ciblé pour limiter l'exposition de tools

- cache `process_document` configurable par appel et via `MISTRAL_MCP_CACHE_DIR`

- bypass du cache pour les documents d'identité activé par défaut, même quand `kind:"auto"` résout en `id_document`

- transport Streamable HTTP + bearer pour déploiements contrôlés / on-premise

- prompts et skills français de série (compte-rendu de réunion, résumé juridique, relance facture, message de commit, réponse email)

- tier Experiment gratuit côté Mistral suffisant pour évaluer (~1 milliard de tokens/mois)

**Ce que ce projet ne prétend PAS être :**

- ce n'est pas une certification RGPD, DORA, HDS ou ISO, et il ne remplace ni une AIPD, ni un vendor review, ni un audit de sécurité, ni une analyse juridique

- les conditions Mistral, la résidence des données, la liste des sous-traitants, les paramètres de rétention et la gestion d'incidents doivent être revus séparément sur [mistral.ai/terms](https://mistral.ai/terms) et [legal.mistral.ai](https://legal.mistral.ai)

- ce repo est maintenu par la communauté, ce n'est pas une intégration Mistral officielle ; rien ici ne modifie vos conditions contractuelles avec Mistral

En pratique, `mistral-mcp` réduit la surface d'intégration à évaluer. Il ne remplace pas le travail juridique et conformité lui-même.

---

## Démarrage rapide

**Claude Code** (recommandé — auto-installe, demande la clé API, ship 11 skills) :

```text

/plugin install mistral-mcp@swih-plugins

```

**Cursor / Zed / Windsurf / Claude Desktop** — ajoutez à votre JSON de config MCP :

```json

{

  "mcpServers": {

    "mistral": {

      "command": "npx",

      "args": ["-y", "mistral-mcp@latest"],

      "env": { "MISTRAL_API_KEY": "votre_cle" }

    }

  }

}

```

**Enregistrement manuel Claude Code :**

```bash

claude mcp add mistral -- npx -y mistral-mcp@latest

```

---

## Profils

`MISTRAL_MCP_PROFILE` contrôle le nombre de tools exposés (défaut : `core`).

| Profil | Tools | Quand l'utiliser |

|---|---|---|

| `core` (défaut) | 8 | Usage agentique quotidien — contexte minimal |

| `admin` | 26 | Surface API complète — embeddings, streaming, batch, classify, files, agents, TTS, extraction documentaire. Pour debug, CI, scripts. |

| `workflows` | 3 | Orchestration de pipeline uniquement |

| `metier-docs` | 9 | Vertical documents — core + macro-tool `process_document` |

> `full` est accepté comme alias déprécié de `admin` pour rétro-compatibilité.

```bash

MISTRAL_MCP_PROFILE=admin npx mistral-mcp

```

---

## Tools

### Profil core (12 tools — toujours disponibles)

| Tool | Ce qu'il fait |

|---|---|

| `mistral_chat` | Complétion de chat. Supporte tous les modèles Mistral, `response_format`, `reasoning_effort` pour Magistral. |

| `mistral_vision` | Chat multimodal avec images (URL ou base64). |

| `mistral_ocr` | Document AI — extrait texte, bbox et annotations JSON depuis PDFs/images. Passez `includeBlocks: true` pour les blocs OCR 4 au niveau paragraphe (text/title/table/image/equation/... avec bounding boxes). |

| `codestral_fim` | Complétion de code fill-in-the-middle (modèle Codestral). |

| `voxtral_transcribe` | Audio → texte. Passez `diarize: true` pour la séparation par locuteur. |

| `workflow_execute` | Démarre un Mistral Workflow (exécution durable Temporal). |

| `workflow_status` | Interroge un workflow en cours — retourne `RUNNING \| COMPLETED \| FAILED \| ...`. |

| `workflow_interact` | Signale / interroge un workflow en cours. Utilisé pour les checkpoints humains-dans-la-boucle. |

| `connectors_list` | Découvre les Connecteurs Mistral (intégrations MCP/HTTP) visibles par l'appelant. |

| `connectors_get` | Récupère les métadonnées publiques d'un connecteur (jamais les credentials). |

| `connectors_list_tools` | Liste les tools MCP exposés par un connecteur, avec leur schéma d'entrée. |

| `connectors_call_tool` | Invoque un tool d'un connecteur — passthrough du `CallToolResult` MCP réel. |

### Vertical documents (`MISTRAL_MCP_PROFILE=metier-docs`)

| Tool | Ce qu'il fait |

|---|---|

| `process_document` | Macro-tool en un appel : OCR → classification (kind=auto) → extraction typée → validation → cache. Kinds : `contract` / `invoice` / `id_document` / `generic`. Retourne une union discriminée. Cache PII-safe (auto-bypass id_document). `minOcrConfidence` configurable. |

### Profil admin uniquement (+18 tools, `MISTRAL_MCP_PROFILE=admin`)

| Groupe | Tools |

|---|---|

| Génération | `mistral_chat_stream`, `mistral_embed`, `mistral_tool_call` |

| Agents | `mistral_agent`, `mistral_moderate`, `mistral_classify` |

| Audio | `voxtral_speak` (TTS) |

| Fichiers | `files_upload`, `files_list`, `files_get`, `files_delete`, `files_signed_url` |

| Batch | `batch_create`, `batch_get`, `batch_list`, `batch_cancel` |

| Sampling | `mcp_sample` (délègue la génération au modèle du client MCP) |

---

## Resources

| URI | Ce qu'elle retourne |

|---|---|

| `mistral://models` | Catalogue de modèles live + alias acceptés |

| `mistral://voices` | Catalogue de voix Voxtral TTS live |

| `mistral://workflows` | Liste live des workflows déployés (utiliser `name` comme `workflowIdentifier`) |

---

## Prompts

Prompts curés avec arguments structurés et support de completion MCP :

| Prompt | Entrée | Sortie |

|---|---|---|

| `french_meeting_minutes` | texte de transcription | Compte-rendu de réunion structuré en français |

| `french_email_reply` | email reçu + contexte | Réponse française soignée |

| `french_commit_message` | git diff | Message Conventional Commits en français |

| `french_legal_summary` | texte juridique | Résumé en français clair + clauses clés |

| `french_invoice_reminder` | débiteur, montant, retard, ton | Lettre de relance B2B en français |

| `codestral_review` | git diff | Code review orientée sécurité / logique / style |

---

## Skills Claude Code (11)

Installez via la marketplace `swih-plugins` pour obtenir ces skills nommés :

**Routage**

- `/mistral-mcp:mistral-router` — sélectionne le bon modèle + tool Mistral pour n'importe quelle tâche

**Code**

- `/mistral-mcp:codestral-review` — récupère le diff courant, lance une review ciblée

**Workflows français**

- `/mistral-mcp:french-commit-message` — message Conventional Commits en français

- `/mistral-mcp:french-meeting-minutes` — audio ou texte → compte-rendu structuré FR

- `/mistral-mcp:french-invoice-reminder` — relance B2B avec ton contrôlé

**Traitement documents & audio**

- `/mistral-mcp:contract-analyzer` — OCR → extraction de clauses avec niveau de risque (JSON)

- `/mistral-mcp:pdf-invoice-extractor` — OCR → champs de facture structurés pour réconciliation

- `/mistral-mcp:audio-dispatch` — transcription + diarisation → plan d'action par locuteur

**Workflows humains-dans-la-boucle**

- `/mistral-mcp:contract-review-workflow` — revue de contrat durable avec portes d'approbation

- `/mistral-mcp:compliance-audit-workflow` — audit multi-étapes avec résultats intermédiaires + décisions

- `/mistral-mcp:research-pipeline-workflow` — recherche par hypothèses avec injection d'amendements

---

## Installation

```bash

# Exécution directe (sans install globale)

npx mistral-mcp

# Installation globale

npm install -g mistral-mcp && mistral-mcp

# Docker

docker build -t mistral-mcp .

docker run -i --rm -e MISTRAL_API_KEY=votre_cle mistral-mcp

# Depuis les sources

git clone https://github.com/Swih/mistral-mcp.git

cd mistral-mcp && npm install && npm run build

node dist/index.js

```

---

## Transport

| Mode | Comment activer | Défaut |

|---|---|---|

| **stdio** | Par défaut | `node dist/index.js` |

| **Streamable HTTP** | `MCP_TRANSPORT=http` ou flag `--http` | `127.0.0.1:3333/mcp` |

Variables HTTP : `MCP_HTTP_HOST`, `MCP_HTTP_PORT`, `MCP_HTTP_PATH`, `MCP_HTTP_TOKEN` (bearer auth), `MCP_HTTP_ALLOWED_ORIGINS`, `MCP_HTTP_STATELESS=1`.

`/healthz` est public et ne touche pas au serveur MCP.

---

## Utilisation comme Mistral Connector (beta)

`mistral-mcp` embarque le transport [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25/) et l'auth bearer que [Mistral Connectors](https://docs.mistral.ai/agents/tools/mcp) requièrent. Guides de déploiement Cloudflare Tunnel, Fly.io et Render dans [`examples/deploy/README.md`](./examples/deploy/).

| Surface | Statut |

|---|---|

| Clients MCP locaux (Claude Code, Cursor, Zed, Windsurf, Claude Desktop) | Stable |

| Transport Streamable HTTP + auth bearer | Testé localement (handshake + 401 + initialize vérifiés) |

| Enregistrement Connector via `POST /v1/connectors` | **Guide fourni — Connectors est une feature beta, l'API peut évoluer** |

| Appels Connector depuis Conversations/Agents | Non testé end-to-end (nécessite un déploiement HTTPS public) |

| Auth Connector OAuth 2.1 | À venir — bearer uniquement aujourd'hui |

```bash

curl -X POST https://api.mistral.ai/v1/connectors \

  -H "Authorization: Bearer $MISTRAL_API_KEY" \

  -d '{"name":"mistral_self","server":"https://votre-deploy/mcp","visibility":"private"}'

```

> Mistral Connectors exposent **uniquement les tools** aujourd'hui. Resources, prompts, sampling et elicitation restent disponibles via les clients locaux.

---

## Comparaison avec d'autres serveurs MCP Mistral

| Projet | Périmètre | Idéal pour |

|---|---|---|

| **mistral-mcp** | API Mistral complète + Workflows + 11 skills Claude Code | Tout-en-un auto-hébergé |

| `mcp-mistral-ocr` (communauté) | OCR uniquement | Setup OCR léger |

| Speakeasy `mistral-mcp-server-example` | Démo générée | Référence / template SDK |

| Composio `mistral_ai` toolkit | Tools Mistral routés en SaaS | Hébergé, sans infra |

`mistral-mcp` se différencie en combinant OCR, diarisation Voxtral, FIM Codestral, et Workflows durables Temporal dans un seul serveur, avec prompts français par défaut et une marketplace de plugins Claude Code.

---

## Développement

```bash

npm run dev      # tsx watch

npm run build    # tsc → dist/

npm run lint     # tsc --noEmit

npm test         # 190+ tests (unit + contract + stdio e2e + live API)

npm run inspector

```

Pyramide de tests : unit → contract → stdio e2e → live API (nécessite `MISTRAL_API_KEY`).

---

## Licence

MIT — Copyright Dayan Decamp

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/Swih/mistral-mcp

Awesome Lists containing this project

README