MinerU MCP Server源码发布！打通大模型与MinerU，让 PDF 文档处理更 easy

type

status

date

slug

summary

一、什么是 MCP？

先来明确一下三个概念：

● MCP（Model Context Protocol）是一个开放的模型上下文协议，用于大语言模型与外部数据源和工具之间的标准化连接；

● MinerU API 是负责执行核心文档转换任务（例如，PDF 到 Markdown）的后端服务；

● MinerU MCP Server 则充当一个中间层或桥梁，它将 MinerU API 的功能封装成符合 MCP 规范的接口。

简而言之，MinerU MCP Server 接收来自支持 MCP 协议的客户端（如 Claude、Cursor、Cherry Studio）的指令，然后调用 MinerU API 完成实际的转换工作，并将结果返回给客户端。这种架构使得任何支持 MCP 协议的AI 工具都能方便地集成和使用 MinerU 的文档处理能力。

所以，要想在大模型、Agent里用 MinerU 工具处理 PDF 文档，则需要依次配置 MinerU API、MinerU-MCP，快来看看怎么做吧~

二、使用 MinerU 官方 API 服务

如果你想使用MinerU官方 API 服务而不是本地服务，需要进行以下配置：

1. 获取 MinerU API 密钥

● 访问 MinerU官网

● 注册并登录账号

● 在用户中心找到 API 密钥申请入口

● 按照指引完成 API 密钥申请

2. 配置环境变量

在源码模式下，编辑 .env 文件：

在包管理模式下，设置环境变量：

Windows：

macOS/Linux：

三、MinerU MCP 服务配置

MinerU MCP 服务有两种安装和配置方式：源码模式和包管理模式。下面我们分别介绍这两种方式。

方式一：本地部署模式

1. 配置本地 MinerU 服务

首先，我们需要启动本地的 MinerU 服务：

上述命令将在 http://localhost:8888 启动 MinerU API 服务。

2. 配置 MinerU MCP 服务

接下来，配置和启动 MinerU MCP 服务：

3. 配置环境变量

在 MinerU MCP 目录中创建 .env 文件（可以复制 .env.example 并重命名）：

然后编辑 .env 文件，设置以下内容：

4. 启动 MCP 服务

配置完成后，启动 MCP 服务：

服务将在 http://localhost:8001 启动，使用SSE协议与客户端通信。

方式二：包管理模式（适合生产环境和简单使用）

1. 安装MinerU MCP包

使用pip或uv直接安装mineru-mcp包：

2. 配置环境变量

在这种模式下，我们通过系统环境变量进行配置。

Windows 上设置环境变量：

macOS/Linux上设置环境变量：

注意：如果使用MinerU 官方 API 服务，需要从 MinerU官网(https://mineru.net) 申请 API 密钥，填入 MINERU_API_KEY 字段。

3. 启动 MCP 服务

设置好环境变量后，启动 MCP 服务：

服务将在 http://localhost:8001 启动，使用SSE协议与客户端通信。（* Stdio协议不需要启动，所以下方Cherry Studio的调用案例就不需要启动）

四、MCP常见调用工具与Cherry Studio调用案例

目前，常见的 MCP 接入与调用工具包括：Cursor、Cline（VSCode 插件）、Windsurf、Claude App、Cherry Studio 等。以上工具是我们推荐的接入方式，适用于不同的开发与使用场景，便于用户更高效地集成和体验MinerU MCP 能力。这里我们以Cherry Studio 为例，配置其中的 MinerU-MCP。

1. 进入 Cherry Studio 设置

a. 打开 Cherry Studio 应用程序

b. 点击左下角的"设置"按钮，进入设置页面

c. 在左侧菜单中，选择"MCP 服务器"

在右侧的 MCP 服务器配置界面中，您可以看到已有的 MCP 服务器列表。点击右上角的"添加服务器"按钮来创建新的 MCP 服务，或者点击现有服务来编辑配置。

2. 添加 MinerU-MCP 配置

点击"添加服务器"后，您将看到一个配置表单。请按以下步骤填写：

a. 名称：输入"MinerU-MCP"或您喜欢的其他名称

b. 描述：可选，如"文档转换为Markdown工具"

c. 类型：选择"标准输入/输出（stdio）"

d. 命令：输入 uvx

e. 参数：输入 mineru-mcp

f. 环境变量：添加以下环境变量

使用 uvx 命令可以自动处理 mineru-mcp 的安装和运行，无需预先手动安装 mineru-mcp 包。这是最简单的配置方式。

3. 保存配置

确认无误后，点击界面右上角的"保存"按钮完成配置。保存后，MCP 服务器列表中会显示您刚刚添加的 MinerU-MCP 服务。

4. 使用 Cherry Studio 中的 MinerU MCP

一旦配置完成，您可以在 Cherry Studio 中的对话中使用 MinerU MCP 工具。在 Cherry Studio 中，您可以使用如下提示让模型调用 MinerU MCP 工具。模型会自动识别任务并调用相应的工具。

示例 1: 使用 URL 转换文档

用户输入:

模型将执行的步骤：

模型识别这是文档转换任务，并调用 parse_documents 工具，参数为:

工具处理完成后，模型会告知您转换结果。

（输出示意1）

示例 2: 转换本地文档

用户输入:

模型将执行的步骤：

模型识别这是本地文档转换任务，调用 parse_documents 工具，参数为:

（输出示意2）

示例 3: 启用 OCR 处理扫描文档

用户输入:

模型将执行的步骤：

模型识别这是需要 OCR 处理的文档转换任务，调用 parse_documents 工具，并启用 OCR 参数:

（输出示意3）

示例 4: 完整对话流程

以下是一个完整的对话流程示例：

用户:

模型:

（输出示意4）

5. 工具参数详解

5. 工具参数详解在使用过程中，模型会根据您的指令自动选择合适的工具和参数。以下是主要工具的参数说明：

● parse_documents 工具参数

（点击查看大图）

● get_ocr_languages 工具参数

无需参数，用于获取OCR支持的语言列表。

6. 高级用法

6.1 指定语言和页码范围

用户输入:

6.2 批量处理多个文档

用户输入:

7. 注意事项

● 当设置 USE_LOCAL_API=true 时，使用本地配置的API进行解析

● 当设置 USE_LOCAL_API=false 时，会使用 MinerU 官网的API进行解析

● 处理大型文档可能需要较长时间，请耐心等待

● 如果遇到超时问题，请考虑分批处理文档或使用本地API模式

五、见问题与解决方案

1. 无法启动 MCP 服务

问题：运行 uv run -m mineru.cli 时报错。

解决方案：

● 确保已激活虚拟环境

● 检查是否已安装所有依赖

● 尝试使用 python -m mineru.cli 命令替代

2. 文件转换失败

问题：文件上传成功但转换失败。

解决方案：

● 检查文件格式是否受支持

● 确认API密钥是否正确

● 查看MCP服务日志获取详细错误信息

3. 文件路径问题

问题：使用 parse_documents 工具处理本地文件时报找不到文件错误。

解决方案：请确保使用绝对路径，或者相对于服务器运行目录的正确相对路径。

4. MP 服务调用超时问题

问题：调用 parse_documents 工具时出现 Error calling tool 'parse_documents': MCP error -32001: Request timed out 错误。

解决方案：这个问题常见于处理大型文档或网络不稳定的情况。在某些 MCP 客户端（如 Cursor）中，超时后可能导致无法再次调用 MCP 服务，需要重启客户端。最新版本的 Cursor 中可能会显示正在调用 MCP，但实际上没有真正调用成功。建议：

● 等待官方修复：这是Cursor客户端的已知问题，建议等待Cursor官方修复

● 处理小文件：尽量只处理少量小文件，避免处理大型文档导致超时

● 分批处理：将多个文件分成多次请求处理，每次只处理一两个文件

● 增加超时时间设置（如果客户端支持）

● 对于超时后无法再次调用的问题，需要重启 MCP 客户端

● 如果反复出现超时，请检查网络连接或考虑使用本地 API 模式

本文原载自：ttps://mp.weixin.qq.com/s/pgzNsbReuZ5fRzkRM7JKoA?scene=1