AI导哈

PDF转Markdown工具

一个使用Mistral OCR API将PDF文档转换为Markdown格式的MCP服务器，支持本地文件和URL处理，并能提取和保存图片。

  • by filonenkoalex
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 filonenkoalex/mistral-ocr-mcp

使用说明

Mistral OCR MCP服务器

模型上下文协议（MCP）服务器，使用Mistral的OCR API将PDF文档转换为Markdown。

特性

  • 使用Mistral OCR将PDF文件转换为Markdown格式
  • 支持本地PDF文件和URL
  • 自动上传和处理本地PDF文件
  • 通过环境变量配置输出目录
  • 图像提取：通过自动路径校正从PDF中提取和保存图像
  • 带有页面标记的多页文档支持
  • 保留文档结构、表格和格式

先决条件

安装

1.安装UV（如果尚未安装）

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2.克隆并设置项目

cd mistral-ocr-mcp

# Copy the example environment file
cp .env.example .env

# Edit .env and add your Mistral API key
# MISTRAL_API_KEY=your_api_key_here

3.使用UV安装依赖项

uv sync

配置

创建一个 .env 项目根目录中的文件，包含以下变量：

# Required: Your Mistral API key
MISTRAL_API_KEY=your_api_key_here

# Optional: Output directory for converted files (defaults to ./output)
MISTRAL_OUTPUT_DIR=./output

用法

使用UV运行

# Run directly with uvx (no installation needed)
uvx --from . mistral-ocr-mcp

# Or with uv run
uv run mistral-ocr-mcp

以开发模式运行

uv run python -m mistral_ocr_mcp.server

MCP客户端配置

要将此服务器与MCP客户端（如Claude Desktop）一起使用，请将其添加到MCP配置中：

适用于克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "mistral-ocr": {
      "command": "uvx",
      "args": [
        "--from",
        "C:\\Projects\\GitHub\\mistral-ocr-mcp",
        "mistral-ocr-mcp"
      ],
      "env": {
        "MISTRAL_API_KEY": "your_api_key_here",
        "MISTRAL_OUTPUT_DIR": "C:\\path\\to\\output"
      }
    }
  }
}

或者使用本地路径 uv:

{
  "mcpServers": {
    "mistral-ocr": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Projects\\GitHub\\mistral-ocr-mcp",
        "run",
        "mistral-ocr-mcp"
      ],
      "env": {
        "MISTRAL_API_KEY": "your_api_key_here",
        "MISTRAL_OUTPUT_DIR": "C:\\path\\to\\output"
      }
    }
  }
}

可用工具

convert_pdf_to_markdown

将PDF文档转换为Markdown格式。

参数：

  • source （必填）：本地PDF文件的路径或PDF文档的URL
  • output_filename （可选）：不带扩展名的自定义输出文件名
  • include_images （可选）：是否包含base64编码的图像（默认值：false）

无图像示例：

{
  "source": "C:\\documents\\report.pdf",
  "output_filename": "my_report",
  "include_images": false
}

图像提取示例：

{
  "source": "https://arxiv.org/pdf/2501.00663",
  "output_filename": "research_paper",
  "include_images": true
}

get_output_directory

返回当前输出目录路径。

详细功能

本地PDF处理

服务器通过以下方式处理本地PDF：

  1. 将文件上传到Mistral的安全存储
  2. 生成已签名的URL
  3. 使用OCR处理文档
  4. 在本地保存降价输出

基于URL的处理

通过URL访问的PDF文件直接处理，无需上传：

{
  "source": "https://arxiv.org/pdf/2501.00663"
}

多页文档

每个页面都经过处理，并在输出中标记一条注释：

<!-- Page 1 -->
[Content from page 1]

<!-- Page 2 -->
[Content from page 2]

图像提取

当 include_images 设置为 true，服务器将：

  1. 创建文档文件夹 使用PDF的原始名称
  2. 提取所有图像 从PDF文档
  3. 保存图像 对一个 images/ 文档文件夹中的子目录
  4. 更新降价参考 使用简单的路径 images/img-X.jpeg
  5. 保留图像ID 来自Mistral OCR（例如。， img-0.jpeg, img-1.jpeg)
  6. 保存markdown文件 在图像旁边的文档文件夹中

转换图像后的目录结构：

output/
└── research_paper/
    ├── research_paper.md
    └── images/
        ├── img-0.jpeg
        ├── img-1.jpeg
        └── img-2.jpeg

每个PDF转换都会创建自己的文件夹，其中包含：

  • markdown文件（与PDF同名+ .md)
  • 一 images 包含所有提取图像的子文件夹

带图像的Markdown输出：

<!-- Page 1 -->
# Document Title

Here is a chart showing the results:

![img-0.jpeg](images/img-0.jpeg)

The data shows...

图像引用使用简单的相对路径 images/img-X.jpeg，它在所有markdown查看器中都能可靠地工作。

图像格式：

  • 图像是从OCR响应中的base64编码数据URI中提取的
  • base64数据被解码并保存为二进制图像文件
  • 以原始格式保存（通常为JPEG或PNG）
  • Markdown引用会自动更新为使用相对路径
  • 可以在支持相对路径的markdown查看器中直接查看

它是如何工作的：

  1. 在输出目录中创建一个具有PDF原始名称的文件夹
  2. Mistral OCR将图像作为base64编码的数据URI返回（例如。， data:image/jpeg;base64,/9j/4AAQ...)
  3. 服务器提取base64部分，将其解码为二进制数据
  4. 将每个图像及其ID保存为文件名（例如。， img-0.jpeg)在 images/ 子文件夹
  5. 使用简单的相对路径将markdown更新为参考图像 images/img-X.jpeg
  6. 将markdown文件保存在与图像相同的文件夹中

注： 图像提取增加了处理时间和API响应大小。仅在需要保留PDF中的图表、图解、照片或插图等视觉元素时启用。

局限性

  • PDF文件必须小于50 MB
  • 每个请求最多1000页
  • 支持的文件格式：仅PDF

定价

Mistral OCR每1000页收费1美元（每页0.001美元）。检查 Mistral的定价页面 以目前的价格。

故障排除

“需要MISTRAL_API_KEY环境变量”

确保您已创建 .env 使用API密钥文件，或在MCP客户端配置中设置环境变量。

“找不到文件”错误

确保PDF文件路径是绝对的，并且文件存在。在Windows上，在路径中使用双反斜杠或正斜杠。

权限错误

确保输出目录存在并且可写。如果它不存在，服务器将尝试创建它。

VS代码在markdown预览中不显示图像

如果图像未显示在VS Code的markdown预览中：

  1. 检查文件结构：新的文件夹结构使所有内容都井然有序：

    output/
└── document_name/
    ├── document_name.md
    └── images/
        ├── img-0.jpeg
        └── img-1.jpeg

  2. 验证图像路径：打开markdown文件并检查图像引用：

    • 应该是： ![img-0.jpeg](images/img-0.jpeg)
    • 使用简单 images/ 路径（不是带空格的复杂文件夹名）
    • 使用正斜杠 / （不是反斜杠 \)
    • 路径相对于markdown文件

  3. 打开文档文件夹：导航到文档文件夹（例如。， output/document_name/)然后从那里打开markdown文件。VS Code从markdown文件的位置解析相对路径。

  4. 检查实际图像文件是否存在：导航到 images/ 子文件夹并验证 .jpeg 文件在那里，可以打开。

  5. 重新启动VS代码：有时VS Code的markdown预览缓存需要刷新。关闭并重新打开VS Code，或从命令面板运行“开发人员：重新加载窗口”。

简化的文件夹结构 images/ 避免了路径中空格和特殊字符的问题。

发展

项目结构

mistral-ocr-mcp/
├── mistral_ocr_mcp/
│   ├── __init__.py
│   └── server.py          # Main MCP server implementation
├── pyproject.toml         # UV project configuration
├── .env.example           # Example environment variables
├── .gitignore
└── README.md

运行测试

# Install dev dependencies
uv sync --dev

# Run tests (when added)
uv run pytest

许可证

麻省理工学院

参考文献

相关 MCP