MinerU × Cherry Studio通过 MCP 把文档解析能力接入多模型 AI 客户端【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU本文介绍如何将 MinerU 的文档解析能力以 MCPModel Context Protocol服务形式接入多模型 AI 客户端 Cherry Studio从 MCP 服务器配置的填写、环境变量含义、parse_documents等工具参数到 URL/本地文件/扫描版文档等典型对话场景并基于 MinerU 仓库源码梳理本地 API 模式USE_LOCAL_API背后对应的 FastAPI 服务端点帮助你在 Cherry Studio 的知识库与对话中直接用自然语言完成 PDF 到 Markdown/JSON 的转换。一、集成背景Cherry Studio 与 MinerU-MCPCherry 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 的解析能力已深度集成到其知识库与对话交互中为用户带来更便捷的文档处理与信息获取体验。从接入方式看整条链路如下Cherry Studio 作为 MCP 客户端按stdio标准输入/输出方式拉起一个子进程该子进程由uvx mineru-mcp命令启动即 MinerU 官方提供的 MCP Server 包uvx会自动处理 mineru-mcp 的安装和运行无需预先手动安装 mineru-mcp 包这是最简单的配置方式MCP Server 根据环境变量决定走云端解析还是本地解析USE_LOCAL_APIfalse时使用 MinerU 官网的 API 进行解析USE_LOCAL_APItrue时使用本地配置的 API 进行解析即本机自建的 MinerU 服务。二、进入 Cherry Studio 的 MCP 服务器设置打开 Cherry Studio 应用程序点击左下角的设置按钮进入设置页面在左侧菜单中选择MCP 服务器。在右侧的 MCP 服务器配置界面中可以看到已有的 MCP 服务器列表。点击右上角的添加服务器按钮来创建新的 MCP 服务或者点击现有服务来编辑配置。三、填写 MinerU-MCP 配置点击添加服务器后会看到一个配置表单。请按以下步骤填写表单字段填写内容说明名称MinerU-MCP或自定义在客户端中显示的服务名描述文档转换为Markdown工具可选便于识别用途类型标准输入/输出stdio以子进程方式启动 MCP Server命令uvx通过 uv 工具执行自动安装并运行包参数mineru-mcp待运行的包名环境变量见下表决定解析端点、密钥与输出目录环境变量在环境变量一栏逐项添加MINERU_API_BASEhttps://mineru.net MINERU_API_KEY您的API密钥 OUTPUT_DIR./downloads USE_LOCAL_APIfalse LOCAL_MINERU_API_BASEhttp://localhost:8888各变量含义MINERU_API_BASE云端解析服务地址默认指向 MinerU 官网 APIMINERU_API_KEY在云端模式USE_LOCAL_APIfalse下必需的 API 密钥用于身份认证与配额计费OUTPUT_DIR转换产物Markdown、中间 JSON、图片等的落地目录示例中为相对路径./downloadsUSE_LOCAL_API模式开关。false走官网 APItrue切换到本地 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适用于扫描版、图片型 PDFlanguage解析语言如 ch中文page_ranges页码范围如 5-10仅解析指定页。参数面板示意这些参数与 MinerU 解析 API 的选项设计一脉相承从源码结构看仓库中定义解析请求选项的 api_request.py 同样暴露了backendpipeline / 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参数为 chpage_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_APItrue 时当设置USE_LOCAL_APItrue时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.pyPOST /file_parse提交文件解析任务并同步等待任务完成后在同一响应中返回解析结果任务失败时返回 409POST /tasks提交异步解析任务立即返回 task_id202GET /tasks/{task_id}查询任务状态GET /tasks/{task_id}/result获取解析结果未就绪时返回 202失败返回 409GET /health健康检查返回任务队列统计、版本与协议版本等信息可用于确认本地服务是否正常。本地模式下MCP Server 提交文件后会得到 Markdown、中间 JSON 等产物这也是文档中处理大型文档可能需要较长时间提示的另一面——本地模式的耗时取决于你的算力配置。启动本地 API 时建议先访问/health端点确认服务就绪再配置USE_LOCAL_APItrue。九、注意事项当设置USE_LOCAL_APItrue时使用本地配置的 API 进行解析当设置USE_LOCAL_APIfalse时会使用 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_APItrue。小结在 Cherry Studio 中接入 MinerU-MCP 的核心就是一个 stdio 服务 五组环境变量uvx mineru-mcp负责拉起解析服务MINERU_API_BASE/MINERU_API_KEY决定云端模式的端点与鉴权USE_LOCAL_APILOCAL_MINERU_API_BASE决定本地模式切换到由 mineru/cli/fast_api.py 提供的 FastAPI 服务。配置完成后parse_documents的 URL/本地文件/OCR/页码范围/批量等用法都可以通过自然语言直接驱动超时类问题则优先通过小文件 分批 本地 API 模式来规避。【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考