# Swih/mistral-mcp [Health: Active]

**Category:** 🛠️ Other Tools and Integrations  
**Repository:** https://github.com/Swih/mistral-mcp  
**GitHub Stars:** 15  
**npm Downloads (last month):** 729  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/swih-mistral-mcp

## Description
MCP server exposing 22 Mistral AI capabilities (chat, OCR, audio, vision, agents, embeddings, moderation, classification, files, batch) with dual transport (stdio + Streamable HTTP), structured outputs on every tool, and 6 curated French/English prompts with argument completion. Vendor API key required.

## Tools
Capabilities this server exposes over MCP:

- **mistral_chat** — 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.
- **codestral_fim** — 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.
- **mistral_vision** — 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`.
- **mistral_ocr** — 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: "<id-from-files-api>" }

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' or 'word'.

Returns `pages[].markdown` plus optional `pages[].hyperlinks`, `header`, `footer`,
`images` bounding boxes, annotations, confidence scores, and `dimensions`.
- **voxtral_transcribe** — 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: "<id-from-files-api>" }

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.
- **workflow_execute** — Start a Mistral Workflow execution.

`workflowIdentifier` is the workflow name or ID (visible in mistral://workflows).
`input` is a free-form JSON object matching the workflow's input schema.

Modes:
  - waitForResult=false (default): returns immediately with execution_id and RUNNING status.
    Poll workflow_status to track completion.
  - waitForResult=true: blocks until the workflow finishes and returns the result inline.
    Use timeoutSeconds (default 30) to cap the wait.

Use deploymentName to target a specific deployment slot when multiple are configured.
- **workflow_status** — Get the current state and result of a workflow execution.

Statuses: RUNNING | COMPLETED | FAILED | CANCELED | TERMINATED |
          CONTINUED_AS_NEW | TIMED_OUT | RETRYING_AFTER_ERROR

Poll until status is COMPLETED (or terminal) when waitForResult was false.
`result` is populated once the workflow reaches a terminal state.
- **workflow_interact** — Send a signal to or run a query against a running workflow execution.

action=signal: fire-and-forget event; the workflow reacts asynchronously.
  - `name`: signal name defined in the workflow.
  - `input`: optional payload matching the signal's schema.

action=query: synchronous read of internal workflow state.
  - `name`: query handler name defined in the workflow.
  - `input`: optional parameters for the query.
  - Returns `query_name` + `result` inline.

action=update: synchronous request to modify workflow state mid-execution.
  - `name`: update handler name defined in the workflow.
  - `input`: optional payload for the update.
  - Returns `update_name` + `result` inline.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mistral-mcp": {
    "command": "npx",
    "args": ["-y","mistral-mcp@1.0.0"],
    "env": {
      "MISTRAL_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `MISTRAL_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Swih/mistral-mcp MCP server does

Swih/mistral-mcp MCP server connects MCP clients to Mistral APIs for text generation, structured document extraction, OCR, image-aware chat, audio transcription, and fill-in-the-middle coding. The default `core` profile exposes six tools covering documents, chat, vision, transcription, and code completion. Other profiles provide workflow orchestration, broader document tools, administration features, or a smaller self-hosted set.

Document processing can accept text or Markdown, document URLs, base64 images, or uploaded file IDs. It supports invoice, contract, identity-document, generic, and automatic classification modes. Typed extraction returns readable content together with structured content, but schema validation checks response shape rather than factual correctness or accounting accuracy.

## How it works

The server receives tool calls over MCP and forwards supported requests to Mistral Cloud or a compatible configured endpoint. Chat responses include assistant text and token usage. OCR returns per-page Markdown and may include tables, headers, footers, links, images, annotations, confidence scores, and dimensions. Voxtral transcription returns text and detected language, with optional speaker segments and timestamps.

Workflow calls can either wait for a result or return an execution identifier immediately. `workflow_status` checks progress, while `workflow_interact` can signal, query, or update a running execution. Chat does not stream; use the separate streaming chat capability where long-output progress is needed and the selected profile exposes it.

## Setup and configuration

To run the Swih/mistral-mcp MCP server, use Node.js 20 or newer, npm, and a Mistral API key with access to the requested models and sufficient quota. A typical stdio configuration runs `npx -y mistral-mcp@1.0.0` and passes `MISTRAL_API_KEY`, `MISTRAL_DEFAULT_MODEL`, and `MISTRAL_MCP_PROFILE` in the client environment.

`MISTRAL_MCP_PROFILE` defaults to `core`. Set it to `metier-docs` for the legacy document and orchestration set, `workflows` for workflow-related tools, `admin` for all implemented tool families, or `self-hosted` for compatible custom endpoints. `full` is a deprecated alias for `admin`. The server reads environment values supplied by the client and does not automatically load `.env` files.

Use `--doctor` to inspect the local profile and tool list without making API calls. The `mistral://capabilities` resource reports the active endpoint and omitted tool families, but neither check confirms account permissions or quota.

## Tools and capabilities

Available capabilities include:

- `process_document` for classification and schema-validated extraction.
- `mistral_chat` for Mistral chat completions and structured response formats.
- `mistral_ocr` for PDF and image OCR.
- `mistral_vision` for text-plus-image requests using URLs or base64 data.
- `voxtral_transcribe` for audio transcription and optional diarization.
- `codestral_fim` for code completion between a prefix and suffix.
- Workflow execution, status, and interaction tools in applicable profiles.

The broader profiles also cover capabilities such as Files, Batch, Conversations, Libraries, connectors, and search-index discovery where implemented by the selected profile.

## Limitations and notes

Swih/mistral-mcp MCP server sends cloud extraction requests to Mistral even when hosted locally. Model availability and free quota depend on the Mistral account. OCR and file-based processing require the relevant API access and quota. Text document inputs must contain non-whitespace content and stay within 60,000 UTF-16 code units.

Review extracted fields against the source before using them operationally. The documented live test covered one synthetic invoice and does not establish general extraction accuracy. Image requests require a vision-capable model, and audio transcription supports the documented Voxtral models. Changing profiles requires restarting the server and refreshing the client's tool catalog.

_Full upstream README: https://allmcps.com/mcp/swih-mistral-mcp/readme_