MistralDocAI MCP 服务器

一个 MCP 服务器，使用 Mistral AI 的 OCR 和视觉模型将文档和图像转换为 Markdown。将其指向 PDF、幻灯片、Word 文档或扫描图像，您的 MCP 客户端即可获得 Markdown 输出。

它适用于已经使用 MCP 客户端（如 Claude Desktop）并希望在客户端内进行文档转换，而不是使用单独工具的用户。

状态： 积极维护，尽力而为，作为个人项目。当前版本为 2.0。从 1.x 升级前，请参阅 版本与兼容性。

语言： 本项目仅使用英文。界面文本、文档和错误消息均为英文，且不发布本地化构建。您处理的文档可以是 Mistral 模型支持的任何语言。

要求

您无需自行安装 Python 依赖。服务器会在首次运行时在 ~/.mistraldocai-mcp/ 下创建虚拟环境。

Related MCP server: Mistral OCR MCP Server

安装

验证您的机器能否运行它：

npx @trsdn/mistraldocai-mcp-server --test

这会创建 Python 环境、安装依赖、导入服务器，并报告其发现。在配置客户端之前运行它，因为它能将静默的客户端故障转化为可读的错误。

配置

您的 API 密钥

要么在客户端启动服务器的环境中导出它：

export MISTRAL_API_KEY=your_key_here

要么将其放入 ~/.mistraldocai-mcp/.env，服务器会在首次运行时生成该文件：

MISTRAL_API_KEY=your_key_here

该文件通常是更可靠的选择，因为桌面 MCP 客户端通常不会继承您的 shell 环境。

Claude Desktop

将此添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "mistraldocai": {
      "command": "npx",
      "args": ["@trsdn/mistraldocai-mcp-server"],
      "env": {
        "MISTRAL_API_KEY": "your_key_here"
      }
    }
  }
}

其他客户端

任何通过 stdio 启动 MCP 服务器的客户端均可使用。使用 npx @trsdn/mistraldocai-mcp-server 作为命令，并在环境中提供 MISTRAL_API_KEY。

工具

process_document

将单个文档或图像转换为 Markdown。提供路径或 base64 内容。

{ "name": "process_document", "arguments": { "file_path": "/path/to/report.pdf" } }

process_directory

将目录中所有受支持的文件转换为 Markdown，每个输入生成一个 .md 文件，并保留目录结构。

get_supported_formats

返回支持的格式及其限制。不接受参数。

支持的格式

限制由 Mistral 的 OCR API 设定：每个文件 50 MB，每个文档 1000 页。定价和吞吐量属于 Mistral，而非本项目；请查看他们的定价页面获取当前数据，而不是相信 README 中复制的数字。

数据与隐私

您处理的文档会发送给 Mistral AI。 这正是服务器的用途，但这也意味着内容会离开您的机器。请勿处理您无权与第三方 AI 提供商共享的材料。

可访问性

控制台输出为纯 ASCII，无颜色、无装饰符号，因此在屏幕阅读器、Windows 终端以及去除格式的客户端日志中均可读。

已知限制：服务器没有自己的界面。您看到的一切都来自您的 MCP 客户端，因此键盘访问、焦点处理和对比度是客户端的行为，而非本项目的。对话视图中的可访问性问题应提交到客户端的 issue 跟踪器。

版本与兼容性

本项目遵循语义化版本控制。主版本号在以下情况提升：Node.js 最低版本提高、Python mcp 依赖跨越主版本，或工具契约发生变化。

从 1.x 升级需要 Node.js 22 或更高版本。1.0.4 及更早版本无法从干净环境安装：其 Python 依赖未限定版本，现在会解析到不兼容的版本。没有受支持的 1.x 回退。完整说明见 CHANGELOG.md。

工作原理

MCP client  --stdio-->  dist/index.js  --spawn-->  python/mcp_server.py  --HTTPS-->  api.mistral.ai
                             |                            |
                    manages ~/.mistraldocai-mcp/    docmistral.py does the
                    venv, deps, and .env            conversion

两个约束解释了大部分设计：

• stdout 是协议。 MCP 客户端将 stdout 解析为 JSON-RPC，因此两种语言的所有诊断信息都发送到 stderr。一个多余的 print 会破坏会话。

• 包目录是只读的。 全局 npm 安装无法写入，因此虚拟环境、.env 和其他所有状态都位于 ~/.mistraldocai-mcp/ 下。

开发

git clone https://github.com/trsdn/MistralDocAI-mcp.git
cd MistralDocAI-mcp
npm ci
npm run build

使用 CI 也运行的单一命令验证更改：

npm run verify

如果您更改了 python/ 下的任何内容，请同时针对已安装 python/mcp_requirements.txt 的解释器运行 ruff check . 和 python3 scripts/verify_python_server.py。

AGENTS.md 包含完整的布局、约定和禁止操作列表。它是为 AI 代理编写的，对人类来说也是最快的入门指南。

项目文档

许可证

MIT。

本仓库依据 trsdn 仓库质量标准 进行评估。结果记录在 .github/conformance.yml 中，各标准的证据见 docs/self-assessment.md。