MinerU × Cherry Studio：通过 MCP 把文档解析能力接入多模型 AI 客户端

本文介绍如何将 MinerU 的文档解析能力以 MCP（Model Context Protocol）服务形式接入多模型 AI 客户端 Cherry Studio：从 MCP 服务器配置的填写、环境变量含义、parse_documents 等工具参数，到 URL/本地文件/扫描版文档等典型对话场景，并基于 MinerU 仓库源码梳理本地 API 模式（USE_LOCAL_API）背后对应的 FastAPI 服务端点，帮助你在 Cherry Studio 的知识库与对话中直接用自然语言完成 PDF 到 Markdown/JSON 的转换。

一、集成背景：Cherry Studio 与 MinerU-MCP

Cherry Studio 是一款功能强大的多模型 AI 客户端软件，支持 Windows、macOS 和 Linux 等多平台运行，集成了 OpenAI、DeepSeek、Gemini、Anthropic 等主流 AI 云服务，同时支持本地模型运行，用户可以灵活切换不同的 AI 模型（官网可检索 Cherry Studio 获取）。

MinerU 是面向 Agentic 工作流的文档解析引擎，可将 PDF、Office 等复杂文档转换为 LLM 可直接消费的 Markdown/JSON。项目 README 中将 "MCP Server" 列为核心集成能力之一，与 Cursor、Claude Desktop、Windsurf 等 AI 编程/对话工具原生集成（见 README_zh-CN.md）。在 Cherry Studio 中，MinerU 的解析能力已深度集成到其知识库与对话交互中，为用户带来更便捷的文档处理与信息获取体验。

从接入方式看，整条链路如下：

1. Cherry Studio 作为 MCP 客户端，按 stdio（标准输入/输出） 方式拉起一个子进程；
2. 该子进程由 uvx mineru-mcp 命令启动，即 MinerU 官方提供的 MCP Server 包，uvx 会自动处理 mineru-mcp 的安装和运行，无需预先手动安装 mineru-mcp 包，这是最简单的配置方式；
3. MCP Server 根据环境变量决定走云端解析还是本地解析：
   • USE_LOCAL_API=false 时，使用 MinerU 官网的 API 进行解析；
   • USE_LOCAL_API=true 时，使用本地配置的 API 进行解析，即本机自建的 MinerU 服务。

二、进入 Cherry Studio 的 MCP 服务器设置

1. 打开 Cherry Studio 应用程序；
2. 点击左下角的"设置"按钮，进入设置页面；
3. 在左侧菜单中，选择"MCP 服务器"。

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

三、填写 MinerU-MCP 配置

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

表单字段	填写内容	说明
名称	MinerU-MCP（或自定义）	在客户端中显示的服务名
描述	文档转换为Markdown工具（可选）	便于识别用途
类型	标准输入/输出（stdio）	以子进程方式启动 MCP Server
命令	uvx	通过 uv 工具执行，自动安装并运行包
参数	mineru-mcp	待运行的包名
环境变量	见下表	决定解析端点、密钥与输出目录

环境变量（在"环境变量"一栏逐项添加）：

MINERU_API_BASE=https://mineru.net
MINERU_API_KEY=您的API密钥
OUTPUT_DIR=./downloads
USE_LOCAL_API=false
LOCAL_MINERU_API_BASE=http://localhost:8888

各变量含义：

• MINERU_API_BASE：云端解析服务地址，默认指向 MinerU 官网 API；
• MINERU_API_KEY：在云端模式（USE_LOCAL_API=false）下必需的 API 密钥，用于身份认证与配额计费；
• OUTPUT_DIR：转换产物（Markdown、中间 JSON、图片等）的落地目录，示例中为相对路径 ./downloads；
• USE_LOCAL_API：模式开关。false 走官网 API，true 切换到本地 API 模式；
• LOCAL_MINERU_API_BASE：本地模式下 MinerU 服务的地址。注意：MinerU 本地 API 服务由仓库中的 fast_api.py 提供，其 CLI 默认监听 127.0.0.1:8000（见 fast_api.py 中 --host、--port 默认值）。示例配置中的 http://localhost:8888 意味着你应以 mineru-api --port 8888 之类的参数把本地服务起在 8888 端口，并保证该值与实际服务地址一致。

保存前请确认：云端模式下 MINERU_API_KEY 已替换为真实密钥；本地模式下 LOCAL_MINERU_API_BASE 可达。

四、保存配置并验证

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

配置完成后的对话界面中，模型即可看到 MinerU MCP 暴露的工具列表：

五、在 Cherry Studio 中使用 MinerU MCP

一旦配置完成，你就可以在 Cherry Studio 的对话中使用 MinerU MCP 工具。用自然语言提示模型调用相应工具即可，模型会自动识别任务并选择合适工具与参数。

示例 1：使用 URL 转换文档

用户输入：

请使用 MinerU MCP 将以下 URL 的 PDF 文档转换为 Markdown 格式：https://example.com/sample.pdf

模型将执行的步骤： 模型识别这是文档转换任务，并调用 parse_documents 工具，参数为：

{"file_sources": "https://example.com/sample.pdf"}

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

示例 2：转换本地文档

用户输入：

请使用 MinerU-MCP 将本地的 D://sample.pdf 文件转换为 Markdown 格式

模型将执行的步骤： 模型识别这是本地文档转换任务，调用 parse_documents 工具，参数为：

{"file_sources": "D://sample.pdf"}

注意：本地文件路径是相对于 MCP 服务器运行目录 解析的，建议优先使用绝对路径（详见"常见问题"中的文件路径问题）。

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

用户输入：

请使用 MinerU-MCP 将以下 URL 的扫描版 PDF 文档转换为 Markdown 格式，并启用 OCR 功能：
https://example.com/scanned.pdf

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

{"file_sources": "https://example.com/scanned.pdf","enable_ocr": true}

示例 4：完整对话流程

用户：
我有一份学术论文的 PDF，网址是 https://arxiv.org/pdf/2303.08774.pdf，能帮我转换成 Markdown 格式吗？

模型：
我可以帮您将这份学术论文转换为 Markdown 格式。我将使用 MinerU-MCP 工具来处理这个任务。
[模型调用 parse_documents 工具，处理过程中...]
论文已成功转换为 Markdown 格式。转换结果如下：
# The Capacity of Diffusion Models to Memorize and Generate Training Data
## Abstract
Recent diffusion models can generate high-quality images that are nearly indistinguishable from real ones...
[显示论文内容...]

六、工具参数详解

在使用过程中，模型会根据你的指令自动选择合适的工具和参数。MinerU-MCP 主要暴露两个工具：

parse_documents 工具参数

核心入参为 file_sources（支持单个 URL/本地路径，多个文档以逗号分隔传入）；可选参数包括：

• enable_ocr：布尔值，是否启用 OCR，适用于扫描版、图片型 PDF；
• language：解析语言，如 "ch"（中文）；
• page_ranges：页码范围，如 "5-10"，仅解析指定页。

参数面板示意：

这些参数与 MinerU 解析 API 的选项设计一脉相承：从源码结构看，仓库中定义解析请求选项的 api_request.py 同样暴露了 backend（pipeline / hybrid-engine / hybrid-http-client 等）、parse_method、language、page_ranges、enable_image_analysis 等字段，MCP 工具层的参数正是对这一解析能力的外露封装。

get_ocr_languages 工具参数

无需参数，用于获取 OCR 支持的语言列表。需要为多语言或特定语种文档指定 language 时，可先调用该工具查询可用取值。

七、高级用法

指定语言和页码范围

用户输入：

请使用 MinerU MCP 将以下 URL 的文档转换为 Markdown 格式，只处理第 5-10 页，并指定语言为中文：https://example.com/document.pdf

模型会使用 parse_documents 工具，并设置 language 参数为 "ch"，page_ranges 参数为 "5-10"。

批量处理多个文档

用户输入：

请使用 MinerU-MCP 将以下多个 URL 的文档转换为 Markdown 格式：
https://example.com/doc1.pdf
https://example.com/doc2.pdf
https://example.com/doc3.pdf

模型会调用 parse_documents 工具，并将多个 URL 以逗号分隔传入 file_sources 参数。

八、本地 API 模式源码级解析（USE_LOCAL_API=true 时）

当设置 USE_LOCAL_API=true 时，mineru-mcp 不走云端，而是把解析任务提交到 LOCAL_MINERU_API_BASE 指向的本地 MinerU 服务。该服务由本仓库提供：

• 入口命令：mineru-api，在 pyproject.toml 中声明为 mineru-api = "mineru.cli.fast_api:main"，对应 fast_api.py 的 main()，最终用 uvicorn 拉起 FastAPI 应用；
• 默认绑定 127.0.0.1:8000，可通过 --host / --port 覆盖，因此使用 8888 端口时需要显式指定 --port 8888；
• 主要服务端点（见 fast_api.py）：
  • POST /file_parse：提交文件解析任务并同步等待，任务完成后在同一响应中返回解析结果；任务失败时返回 409；
  • POST /tasks：提交异步解析任务，立即返回 task_id（202）；
  • GET /tasks/{task_id}：查询任务状态；
  • GET /tasks/{task_id}/result：获取解析结果，未就绪时返回 202，失败返回 409；
  • GET /health：健康检查，返回任务队列统计、版本与协议版本等信息，可用于确认本地服务是否正常。

本地模式下，MCP Server 提交文件后会得到 Markdown、中间 JSON 等产物，这也是文档中"处理大型文档可能需要较长时间"提示的另一面——本地模式的耗时取决于你的算力配置。启动本地 API 时建议先访问 /health 端点确认服务就绪，再配置 USE_LOCAL_API=true。

九、注意事项

• 当设置 USE_LOCAL_API=true 时，使用本地配置的 API 进行解析；
• 当设置 USE_LOCAL_API=false 时，会使用 MinerU 官网的 API 进行解析（需有效 MINERU_API_KEY）；
• 处理大型文档可能需要较长时间，请耐心等待；
• 如果遇到超时问题，请考虑分批处理文档或使用本地 API 模式。

十、常见问题与解决方案

无法启动 MCP 服务

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

解决方案：

• 确保已激活虚拟环境；
• 检查是否已安装所有依赖；
• 尝试使用 python -m mineru.cli 命令替代。

文件转换失败

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

解决方案：

• 检查文件格式是否受支持；
• 确认 API 密钥是否正确；
• 查看 MCP 服务日志获取详细错误信息。

文件路径问题

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

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

MCP 服务调用超时问题

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

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

• 等待客户端官方修复：这是部分客户端的已知问题；
• 处理小文件：尽量只处理少量小文件，避免处理大型文档导致超时；
• 分批处理：将多个文件分成多次请求处理，每次只处理一两个文件；
• 增加超时时间设置（如果客户端支持）；
• 对于超时后无法再次调用的问题，需要重启 MCP 客户端；
• 如果反复出现超时，请检查网络连接或考虑使用本地 API 模式（USE_LOCAL_API=true）。

小结

在 Cherry Studio 中接入 MinerU-MCP 的核心就是"一个 stdio 服务 + 五组环境变量"：uvx mineru-mcp 负责拉起解析服务，MINERU_API_BASE/MINERU_API_KEY 决定云端模式的端点与鉴权，USE_LOCAL_API + LOCAL_MINERU_API_BASE 决定本地模式切换到由 mineru/cli/fast_api.py 提供的 FastAPI 服务。配置完成后，parse_documents 的 URL/本地文件/OCR/页码范围/批量等用法都可以通过自然语言直接驱动；超时类问题则优先通过"小文件 + 分批 + 本地 API 模式"来规避。