mistral-mcp

ドキュメント抽出用 Mistral MCP サーバー

テキストまたは Markdown の請求書を、MCP 経由で型付き JSON に変換します。 mistral-mcp は Mistral チャットを使って取引先、合計金額、明細、支払期日を抽出し、レスポンスのスキーマを検証します。PDF や画像の入力には、オプションで Mistral OCR を利用できます。 process_document は、契約書、身分証明書、自動分類にも対応しています。チャット、ビジョン、文字起こし、コード補完など、デフォルトで 6 つのツールを利用できます。

Français · 移行ガイド · 使用例 · デプロイ

npm パッケージ · 1.0.0 リリースノート · GitHub リリース · Mistral API ドキュメント

バージョン 1.0.0 — 0.11.0 からの破壊的変更： core が 6 つのツールを公開するようになりました。 既存のオーケストレーションクライアントでは、明示的なプロファイルを選択する必要があります。ドキュメントの結果には extraction_source が必須となり、ocr_confidence / page_count は null になる場合があります。 移行とロールバックの手順。

MCP クライアントへのインストール

Node.js 20 以降、npm、および要求するモデルへのアクセス権と利用枠を持つ Mistral API キーが必要です。 mcpServers JSON を使うクライアントでは、stdio サーバーを次のように設定します。

{
  "mcpServers": {
    "mistral": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "MISTRAL_API_KEY": "your_key_here",
        "MISTRAL_DEFAULT_MODEL": "ministral-3b-latest",
        "MISTRAL_MCP_PROFILE": "core"
      }
    }
  }
}

これにより npx -y [email protected] が実行されます。クライアントを再起動し、ツールカタログを更新してください。 サーバーはクライアントから渡された環境変数を読み込みます。.env は自動的に読み込まれません。キーには、クライアントのシークレット設定を使用してください。 テスト用アカウントでは ministral-3b-latest の動作を確認済みです。モデルへのアクセスと無料利用枠はアカウントによって異なります。呼び出しの前に利用上限を確認してください。 MCP をローカルでホストする場合も、抽出リクエストは Mistral に送信されます。

既存のテキストまたは Markdown の請求書をすぐに試す

請求書スクリプトとフィクスチャはソース例であり、npm パッケージには含まれていません。リリースタグをチェックアウトし、リポジトリのルートからビルドします。

git clone https://github.com/Swih/mistral-mcp.git
cd mistral-mcp
git checkout v1.0.0
npm ci
npm run build

キーとチャットモデルを環境変数またはローカルの .env ファイルに設定します。

MISTRAL_API_KEY=your_key_here
MISTRAL_DEFAULT_MODEL=ministral-3b-latest

この例では dotenv を使って .env を読み込みます。キーはバージョン管理に含めないでください。アカウントにクォータがあるチャットモデルを選択してください。デフォルトのモデルではクォータがゼロの場合があります。

npm run example:invoice -- test/fixtures/invoice-text.md --output invoice-result.json

この例では合成 Markdown 請求書を使用します。既存の UTF-8 .txt または .md 請求書を使う場合のコマンド構文は次のとおりです。

node examples/invoice.mjs <local-file.txt|local-file.md> [--output result.json]

スクリプトはテキストをローカルで読み込み、ローカルサーバーの core プロファイルを通じて、source: { type: "text", text: "..." }、kind: "invoice"、options.cache: "bypass" を指定して process_document を呼び出します。テキストには空白以外の内容が含まれている必要があり、60,000 UTF-16 コード単位（JavaScript の文字列長）以内に収める必要があります。Markdown と空白は変更されずに保持されます。Files のアップロードや OCR の呼び出しはありません。請求書の抽出ではテキストが Mistral chat に送信されます。この例では Mistral Cloud のみを使用しますが、キーとチャットクォータは引き続き必要です。処理が完全にローカルで行われるわけではなく、無料であるとも限りません。アカウントの制限を確認してください。

--output を指定しない場合は、検証済みの JSON を出力します。指定した場合は、新しいファイルに書き込み、そのパスを出力します。既存ファイルは上書きされません。出力パスは API 呼び出しの前に確保されるため、失敗後も空のまま残る場合があります。再試行する前に削除するか、新しいパスを選択してください。

2026-09-28、ライブテキストテストと CLI の例は、チャットのみを使用して ministral-3b-latest で成功しました。確認されたフィールドは、ベンダー ACME SAS、合計金額 12960 EUR、支払期日 2026-09-11、および請求書の3項目すべての数量、単価、金額でした。これは合成請求書1件での検証であり、一般的な精度や信頼性を示すスコアではありません。

PDF または画像には、既存の OCR 経路も引き続き利用できます。

npm run example:invoice -- test/fixtures/corpus/invoice-fr-table.pdf --output invoice-ocr-result.json

20 MiB 以下の PDF、PNG、JPEG、WebP ファイルには、Files、OCR、チャットへのアクセスとクォータが必要です。スクリプトはファイルをアップロードし、process_document を呼び出し、抽出に失敗した場合も含め、finally でアップロードの削除を試みます。個別の OCR 準備状況チェックはありません。アップロードとクリーンアップでは Files API を使用し、core で管理者向けツールを公開することはありません。既知の制限： テストアカウントの HTTP 429／OCR クォータゼロにより、ライブ OCR の検証はできませんでした。テキスト処理の成功は OCR 抽出を検証するものではありません。

抽出結果は必ず元の内容と照合してください。合成 PDFとフィクスチャの正解データが示すのは、想定される文書の内容であり、実際に取得された出力ではありません。**スキーマ検証ではレスポンスの形式と型を確認しますが、事実の正確性、請求書の計算、税務処理、会計上の正しさは検証しません。**抽出したフィールドは、使用する前に元の内容と照合してください。

プロファイル

MISTRAL_MCP_PROFILE で5つのプロファイルから選択します。デフォルトは Mistral Cloud 向けの core です。カスタムの MISTRAL_BASE_URL を指定すると、プロファイルを明示的に設定しない限り、self-hosted が自動的に選択されます。

プロファイル	ツール数	1.0.0 での対象範囲
core（デフォルト）	6	ドキュメント、チャット、ビジョン、文字起こし、コード補完
metier-docs	17	旧プロファイルを維持したもの：6つのコアツールに、11個すべてのオーケストレーションツールを追加した構成。以前の16ツールの core の上位集合です
workflows	11	ワークフロー、コネクター、検索インデックスの検出
admin	46	Files、Batch、Conversations、Libraries を含む、このサーバーで実装されているすべてのツール
self-hosted	5	互換性のあるエンドポイントでのチャット、ストリーミングチャット、埋め込み、関数呼び出し、ビジョン

full は引き続き非推奨の admin の別名であり、6つ目のプロファイルではありません。アップグレード後も以前のコアツールセットを維持するには MISTRAL_MCP_PROFILE=metier-docs を設定します。オーケストレーション機能のみを使う場合は workflows、すべてのツールを使う場合は admin を選択してください。プロファイルを変更した後は、サーバーを再起動し、ツールの検出を更新してください。

npx -y [email protected] --doctor を実行すると、API 呼び出しを行わずに、ローカルのプロファイルとツール一覧を確認できます。mistral://capabilities リソースでは、アクティブなエンドポイント、ツールの種類、ツールが除外された理由を確認できます。どちらもアカウントへのアクセス権やクォータを証明するものではありません。

コアツールとドキュメントの動作

ツール	用途
process_document	提供されたテキスト／Markdown、または OCR。請求書、契約書、本人確認書類、一般テキストを対象とした、任意の分類とスキーマ検証済み抽出
mistral_ocr	PDF または画像からの OCR 生テキスト、表、注釈、任意のブロック
mistral_vision	URL または base64 で提供された画像を使ったチャット
mistral_chat	構造化レスポンス形式を含むチャット補完
voxtral_transcribe	話者ダイアライゼーションを任意で指定できる音声文字起こし
codestral_fim	Fill-in-the-middle コード補完

process_document は source: { type: "text", text: string }、ドキュメントの URL、base64 画像、またはアップロード済みファイル ID を受け付けます。テキストには Markdown を 含めることができ、そのまま保持されます。空または空白のみの文字列と、60,000 UTF-16 コード単位を超える 文字列は、generic を含むすべての kind で拒否されます。 kind は auto（デフォルト）、invoice、contract、id_document、または generic です。 成功した呼び出しは、読みやすい content と JSON の structuredContent を返し、失敗した場合は isError: true を返します。

たとえば、以下は合成入力を使用したツール引数であり、実際の結果ではありません。

{
  "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" }
}

キャッシュミス時、または cache: "bypass" の場合、auto はテキストソースであってもチャットを呼び出して 分類します。invoice、contract、id_document はチャットを使って型付き抽出を行います。 テキストソースに対して明示的に kind: "generic" を指定すると、API 呼び出しは行われず、 提供されたテキストが ocr_text と structured_text の両方として返されます。

成功した結果には、次のフィールドがすべて含まれます。

フィールド	提供されたテキスト／Markdown	OCR の成功したソース
extraction_source（必須）	"provided_text"	"mistral_ocr"
ocr_text（名前はそのまま）	元の入力テキスト、そのまま	OCR テキスト
ocr_confidence	null	0 から 1 までの数値
page_count	null	処理されたページ数

• options.maxPages と options.minOcrConfidence は OCR ソースにのみ適用されます。 提供されたテキストのページ分割やスコア付けは行いません。OCR では、信頼度スコアが欠落、不完全、 または無効な場合はエラーになり、指定された最小値を下回る場合もエラーになります。デフォルトの 0.3 は未測定です。OCR 信頼度は抽出精度を保証するものではありません。
• OCR ソースでは、options.maxPages のデフォルトは 50（最大 200）です。型付き抽出では、 OCR テキストが 60,000 UTF-16 コード単位を超えると拒否されます。ドキュメントを分割するか、 OCR テキストには generic を使用してください。テキストソースの入力上限は generic にも適用されます。 options.languageHints は型付き抽出を補助しますが、OCR モデルには適用されません。
• options.cache: "bypass" は、キャッシュの読み取りと書き込みをスキップします。その他のモードは read_only と read_write です。本人確認書類は、auto による分類後も含め、デフォルトでキャッシュを バイパスします。明示的に read_write を指定すると、キャッシュが有効になります。
• キャッシュファイルには抽出されたコンテンツが含まれます。保存場所は MISTRAL_MCP_CACHE_DIR で設定します。 MISTRAL_MCP_CACHE_TTL_HOURS のデフォルトは 168 時間です（0 にすると再利用と新規書き込みが無効になります）。 クリーンアップはキャッシュ操作中に随時行われます。バイパスしても古いエントリは消去されず、有効期限を 過ぎても所定の時刻に削除されるとは限りません。パイプラインバージョン v1.0.0-text.1 によって 古いキャッシュエントリの再利用は無効になりますが、すぐに削除されるとは限りません。

合成コーパスでは、必須の OCR テキストと、抽出されると期待される請求書フィールドを 分けています。npm run eval:docs は、実際の API 呼び出しを通じてこれらを個別に評価します。 フィクスチャの正解データは実際の精度を示すものではありません。テキストベースの合成 PDF では、 劣化したスキャン画像に対する精度は確認できません。 開発と評価に関するガイダンス。

API とデプロイの参考情報

mistral://capabilities は有効なツールセットを記述します。mistral://models は上流カタログを読み取り、API 呼び出しに失敗した場合はフォールバックを報告します。mistral://voices は admin で利用でき、mistral://workflows は metier-docs、workflows、admin で利用できます。カタログに掲載されていても、アクセス権やクォータがあることを意味するわけではありません。

MCP プロセスをホストし、上流エンドポイント、認証情報、ツールの公開範囲、キャッシュポリシーを設定できます。デフォルトでは、リクエストは Mistral Cloud に送信されます。MCP をローカルでホストしても、ドキュメントの推論がローカルになるわけではありません。これらの設定だけでは、データの保存場所や規制への準拠は保証されません。

カスタムの MISTRAL_BASE_URL を指定すると、self-hosted と推定されます。チャット、ストリーミングチャット、埋め込み、関数呼び出し、ビジョンが対象ですが、エンドポイントとモデルの対応状況に依存します。OCR と process_document は含まれません。明示的なプロファイルは推定より優先されますが、バックエンドに不足している API が追加されるわけではありません。

参考情報	内容
移行	削除されたコアツール、明示的なプロファイル、固定された 0.11.0 のフォールバック
例	ローカルの請求書、文字起こし、ライブラリを利用した会話
ツールファミリー と MCP ツールの入力スキーマ	ツールの完全な所属一覧と引数のリファレンス
プロンプト	議事録、メールへの返信、コミット、法務要約、請求書のリマインダー、コードレビュー
デプロイ と .env.example	Docker、Compose、Kubernetes、カスタムエンドポイント、キャッシュ、HTTP 設定
パブリックコネクターガイド	HTTPS デプロイ。パブリックコネクターの呼び出しは、ここではエンドツーエンドで検証済みとは確認されていません
Claude Code プラグイン	11 個のスキルを含むオプションのプラグイン。[email protected] に固定
コントリビューション	ビルド、テスト、評価、リリースの確認
変更履歴 と セキュリティポリシー	変更内容とセキュリティ報告

デフォルトのトランスポートは stdio です。--http または MCP_TRANSPORT=http を指定すると、デフォルトで 127.0.0.1:3333/mcp に Streamable HTTP が有効になり、ベアラー認証と許可するオリジンを設定できます。OAuth は統合されていません。ツールの監査記録は stderr に出力され、引数と結果のペイロードは省略されます。MISTRAL_MCP_AUDIT=off を指定すると、監査記録は無効になります。

プロトコル世代のテストでは、同じ登録を使用して MCP 2026-07-28 と 2025 のハンドシェイクを検証します。npm run check:release は、ビルドとローカルテストに加え、API スタブに対するインストール済みパッケージのテストも確認します。ライブ API の検証は別途行われます。スキップされたテストは成功とは見なされません。パッケージを固定しても、将来にわたる上流の利用可能性や互換性は保証されません。

MIT ライセンス — Copyright Dayan Decamp。