mistral-mcp

用于文档提取的 Mistral MCP 服务

通过 MCP 将文本或 Markdown 发票转换为带类型的 JSON。 mistral-mcp 使用 Mistral 聊天功能提取供应商、总额、明细项和到期日期，然后 验证响应架构。可选的 Mistral OCR 支持 PDF 和图像输入。 process_document 还支持合同、身份证件和自动分类。 默认提供六种工具，包括聊天、视觉、转录和代码补全。

Français · 迁移指南 · 示例 · 部署

npm 软件包 · 1.0.0 版本说明 · GitHub 版本发布 · Mistral API 文档

版本 1.0.0 — 相较于 0.11.0 存在破坏性变更： core 现在提供六种工具； 现有编排客户端必须选择明确的配置。文档结果要求包含 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 配置调用 process_document，传入 source: { type: "text", text: "..." }、kind: "invoice" 和 options.cache: "bypass"。文本必须包含非空白内容，且长度不得超过 60,000 个 UTF-16 代码单元（JavaScript 字符串长度）。Markdown 和空白字符会原样保留。此过程不会上传文件，也不会调用 OCR；发票信息提取会将文本发送给 Mistral chat。 此示例仅使用 Mistral Cloud，仍然需要密钥和聊天额度； 处理并非完全在本地进行，也不保证免费。请查看账户的 限制。

未指定 --output 时，脚本会打印经过验证的 JSON；指定后，会将其写入新文件并 打印该文件路径。不会覆盖已有文件。API 调用前会预留输出路径，失败后该文件可能仍为空；重试前请删除该文件或选择新路径。

2026-09-28，实时文本测试和 CLI 示例使用 ministral-3b-latest 成功运行，仅使用了聊天功能。验证过的字段 包括供应商 ACME SAS、总额 12960 EUR、到期日 2026-09-11，以及三条发票明细的数量、 单价和金额。这仅验证了一张合成发票，并非普遍的准确性或可靠性评分。

对于 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 用于选择五种配置档案之一。对于 Mistral Cloud，默认值为 core；如果自定义 MISTRAL_BASE_URL，则会推断为 self-hosted，除非你显式设置 配置档案。

配置档案	工具	1.0.0 中的范围
core（默认）	6	文档、聊天、视觉、转录和代码补全
metier-docs	17	保留的旧版配置档案：六种核心工具加全部 11 种编排工具；是旧版 16 种核心工具集的超集
workflows	11	工作流、连接器和搜索索引发现
admin	46	此服务实现的所有工具，包括 Files、Batch、Conversations 和 Libraries
self-hosted	5	在兼容端点上使用聊天、流式聊天、嵌入、函数调用和视觉

full 仍是已弃用的 admin 别名，并非第六种配置档案。升级后，设置 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	代码中间填充补全

process_document 接受 source: { type: "text", text: string }、文档 URL、base64 图像或已上传文件的 ID。文本可以包含 Markdown，并会 原样保留；对于所有 kind，包括 generic，空字符串、仅含空白字符的字符串 以及超过 60,000 个 UTF-16 代码单元的字符串都会被拒绝。 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）。类型化提取会拒绝 超过 60,000 个 UTF-16 代码单元的 OCR 文本：请拆分文档，或对 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，并支持配置 Bearer 身份验证和允许的来源。未提供集成式 OAuth。工具审计记录会写入 stderr，且不包含参数和结果负载；MISTRAL_MCP_AUDIT=off 可禁用这些记录。

协议版本测试使用相同的注册项，覆盖 MCP 2026-07-28 和 2025 握手。npm run check:release 会检查构建和本地测试，包括使用 API 存根测试已安装的程序包。实时 API 验证单独进行；跳过的测试不算成功。固定程序包版本不能保证上游将来仍可用或兼容。

MIT 许可证 — 版权所有 Dayan Decamp。