MinerU 教程第三弹：零基础用 n8n 调用 MinerU MCP 搭建文档处理自动化系统

1. 为什么零基础也要用 n8n 调 MinerU MCP 做文档处理自动化如果你手里有一堆 PDF 合同、扫描版论文、带公式的技术手册想批量转成 Markdown 再抽取字段归档纯手工复制粘贴基本等于自虐。MinerU 能把这些文档转成结构化 Markdown支持 OCR、公式和表格识别n8n 是开源可视化工作流工具拖几个节点就能把「上传文件 → 解析 → 大模型抽取 → 写盘归档」串成一条流水线。两者通过 MCPModel Context Protocol对接后你不需要写复杂代码只要在 n8n 里配好 MCP Client 节点就能让大模型直接调用 MinerU 的解析能力。这套组合适合谁适合不想碰 Python 脚本的运营、法务、科研助理也适合想快速验证文档自动化链路的开发者。我实测下来最省事的路径是本地起一个 MinerU MCP Servern8n 里用 MCP Client 节点连上它再挂一个大模型对话节点做触发和字段抽取最后用 Write Files 节点落盘。整条链路跑通后你丢一个 PDF 进去出来的就是 Markdown 加结构化 JSON。这里有个关键点n8n 本身不直接解析 PDF它负责编排MinerU MCP 负责真正的解析和 OCR大模型负责理解你的自然语言指令比如「把这份合同里的甲方、金额、签署日期抽出来」。三者分工明确你只需要把连接参数填对。为了让大模型调用更稳定我建议用 TaoToken 作为模型接入层。它的 API 地址是 https://taotoken.net/api兼容 OpenAI 格式n8n 的 OpenAI 凭证里把 Base URL 填成这个就行。这样你既可以用 GPT-4o-mini 这类模型做对话触发也能在后续扩展里换成其他模型不用改工作流结构。TaoToken 官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册后到 API Keys 页面生成密钥即可。2. 前置准备MinerU MCP Server 与 n8n 环境搭建在 n8n 里连 MCP 之前你得先把 MinerU MCP Server 跑起来。这个 Server 是一个本地服务默认监听 8000 端口提供 SSE 接口给 n8n 调用。安装方式推荐用 uv比 pip 快且依赖隔离干净。如果你还没装 uv先执行pip install uv uv --version然后拉取 MinerU MCP Server 的源码并启动。假设你已经把源码放到本地目录进入该目录后执行uv run mineru-mcp-server --host 0.0.0.0 --port 8000启动成功后终端会提示 SSE 端点通常是http://localhost:8000/sse。你可以先用 curl 验证一下服务是否活着curl -N http://localhost:8000/sse如果看到持续的事件流输出不要按 CtrlC另开终端说明 MCP Server 正常。注意这个服务需要能访问 MinerU 的解析能力所以你的 MinerU API Key 要提前配好通常通过环境变量传入比如MINERU_API_KEY你的key。接下来装 n8n。Node.js 14 是硬性要求建议用 18 或 20。全局安装npm install n8n -g n8n startn8n 默认在http://localhost:5678启动。第一次打开会让你设置管理员账号随便填一个你能记住的邮箱和密码。进入后左侧菜单点 Workflows准备创建新工作流。这里有个容易踩的坑n8n 和 MinerU MCP Server 如果不在同一台机器localhost要换成实际 IP如果都在本机但 n8n 跑在 Docker 里那localhost指向的是容器内部得用host.docker.internal或者宿主机的局域网 IP。我试过在 Docker 里直接填 localhost结果一直连不上换成宿主 IP 才通。另外MCP 调用可能比较慢尤其是大 PDF 带 OCR 的时候。n8n 默认的 MCP 超时时间偏短建议在启动 n8n 前设置环境变量export NODES_MCP_TIMEOUT3600000 n8n start3600000 毫秒等于 1 小时足够处理大部分文档。如果你在 Windows PowerShell 里用$env:NODES_MCP_TIMEOUT3600000。3. 可复制配置n8n 工作流节点与 MCP 连接参数现在进入核心部分。打开 n8n点右上角 Create Workflow你会看到一个空白画布。我们需要依次添加这几个节点Chat Trigger对话触发、AI Agent大模型代理、MCP Client Tool连接 MinerU MCP、Write Files from Disk落盘归档。先配大模型凭证。点左侧 Credentials → Add Credential → 选 OpenAI。在 API Key 里填你在 TaoToken 生成的密钥Base URL 填https://taotoken.net/api。保存后回到画布。然后添加 AI Agent 节点。在 Agent 的 Model 里选刚才的 OpenAI 凭证Model ID 填gpt-4o-mini或者你账号里可用的其他模型。Agent 的 System Prompt 可以写你是一个文档处理助手。当用户上传文件时调用 MinerU MCP 的 parse_documents 工具解析文件然后根据用户指令抽取字段并以 JSON 返回。接着添加 MCP Client Tool 节点把它连到 AI Agent 的 Tool 接口。在 MCP Client 配置里SSE Endpoint 填http://localhost:8000/sse如果你改了 MinerU MCP Server 的端口或 IP这里同步改。保存后n8n 会自动拉取该 MCP Server 暴露的工具列表你应该能看到parse_documents之类的工具名。再添加 Write Files from Disk 节点用于把解析结果写到本地。File Path 填一个绝对路径比如/Users/yourname/mineru_output/{{ $now.toFormat(yyyyMMdd_HHmmss) }}.mdWindows 下写成D:\\mineru_output\\{{ $now.toFormat(yyyyMMdd_HHmmss) }}.md。注意路径里的反斜杠要双写或者直接用正斜杠n8n 在 Windows 上也能识别正斜杠。最后把 Chat Trigger 连到 AI Agent 的输入AI Agent 的输出连到 Write Files。整个工作流的 JSON 结构大致如下你可以直接复制到 n8n 的 Import from Clipboard{ nodes: [ { parameters: { public: true, mode: webhook }, name: Chat Trigger, type: n8n/n8n-nodes-langchain.chatTrigger, position: [200, 300] }, { parameters: { model: gpt-4o-mini, options: {} }, name: AI Agent, type: n8n/n8n-nodes-langchain.agent, position: [500, 300] }, { parameters: { endpoint: http://localhost:8000/sse }, name: MCP Client, type: n8n/n8n-nodes-langchain.mcpClientTool, position: [500, 500] }, { parameters: { filePath: /Users/yourname/mineru_output/{{ $now.toFormat(yyyyMMdd_HHmmss) }}.md }, name: Write Files from Disk, type: n8n-nodes-base.writeBinaryFile, position: [800, 300] } ], connections: { Chat Trigger: { main: [[{node: AI Agent, type: main, index: 0}]] }, MCP Client: { ai_tool: [[{node: AI Agent, type: ai_tool, index: 0}]] }, AI Agent: { main: [[{node: Write Files from Disk, type: main, index: 0}]] } } }导入后记得把 Write Files 的路径改成你自己的MCP Client 的 endpoint 也确认一下。如果你用的是 TaoToken 的 Coding Plan 做长期编码任务可以把模型换成更适合代码和结构化输出的型号Base URL 和 Key 不变。4. 端到端验证上传 PDF 看 Markdown 与归档结果配置保存后点画布下方的 Open Chat 按钮会弹出一个对话窗口。在窗口里点回形针图标上传一个 PDF比如一份带表格的发票或者论文首页。然后输入指令请解析这个文件把正文转成 Markdown并抽取标题、作者、日期三个字段以 JSON 返回。点发送。你会看到 AI Agent 开始工作它先调用 MCP Client 的parse_documents工具把文件传给 MinerU MCP ServerMinerU 解析完成后返回 Markdown 文本大模型再根据你的指令抽取字段。整个过程在对话窗口里能看到工具调用日志。如果一切正常Write Files 节点会把结果写到指定路径。打开那个文件你应该能看到类似这样的内容# 文档标题 作者张三 日期2024-05-20 ## 正文 这里是 MinerU 解析出来的 Markdown 正文表格和公式都保留为 Markdown 格式。同时对话窗口里会返回 JSON{ title: 文档标题, author: 张三, date: 2024-05-20 }这说明整条链路跑通了。你可以再试一个扫描版 PDF验证 OCR 是否生效。如果 MinerU 返回的 Markdown 里文字正确说明 OCR 也正常。验证模型对话是否稳定可以到 TaoToken 的模型对话页面单独测一下同一个模型地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。这样能把「模型本身的问题」和「n8n 工作流的问题」分开排查。批量归档的场景你可以把 Chat Trigger 换成 Webhook 或者 Schedule Trigger配合一个循环节点遍历文件夹里的所有 PDF。不过零基础阶段先把单文件跑通再扩展批量否则出错时很难定位是哪个环节的问题。5. 常见报错排查401、local proxy failed、reading choices、OAuth第一个高频报错是 401 Unauthorized。如果你在 n8n 的 OpenAI 凭证里填了 TaoToken 的 Key 但没改 Base URL请求会打到 OpenAI 官方自然 401。检查 Credentials 里的 Base URL 是不是https://taotoken.net/apiKey 有没有多余空格。另外TaoToken 的 Key 是在 API Keys 页面生成的别把登录密码当 Key 填进去。第二个是local proxy failed或连接被拒绝。这通常是 n8n 连不上 MinerU MCP Server。先确认 MCP Server 还在运行终端没关。然后确认 endpoint 写的是/sse结尾不是/mcp或根路径。如果 n8n 在 Docker 里把localhost换成host.docker.internal。防火墙也可能拦Windows 上检查一下 8000 端口是否允许入站。第三个是reading choices相关报错比如Cannot read properties of undefined (reading choices)。这多半是模型返回格式不符合预期常见原因是 Base URL 填错导致返回了 HTML 错误页或者模型 ID 写错。检查 Model ID 是否在你账号的可用列表里TaoToken 的模型列表可以在控制台看到。另外如果 Agent 的 System Prompt 太复杂模型可能返回非 JSON也会触发解析错误先把 Prompt 简化再试。第四个是 OAuth 相关报错。n8n 某些节点会走 OAuth 流程但 MCP Client 和 OpenAI 凭证都不需要 OAuth。如果你看到 OAuth 报错大概率是误点了其他凭证类型删掉重新建一个 OpenAI 类型的凭证即可。TaoToken 的接入文档里有各语言的调用示例地址是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 对照检查请求头格式。还有一个隐蔽的坑MCP 超时。如果 PDF 很大n8n 可能在 MCP 返回前就断了。确认启动 n8n 前设置了NODES_MCP_TIMEOUT并且值足够大。如果还是超时把 PDF 拆小再试或者检查 MinerU MCP Server 那边的日志有没有报错。6. 把链路用起来从单文件到批量归档的下一步单文件跑通后你可以把工作流改成批量模式。具体做法加一个 Read Files from Disk 节点读取文件夹接一个 Loop Over Items 节点把每个文件依次传给 AI Agent。Write Files 的路径里用{{ $itemIndex }}或者文件名变量避免覆盖。如果你想让整个系统长期跑在服务器上n8n 可以用 Docker 部署MinerU MCP Server 也做成 systemd 服务或者 Docker 容器。TaoToken 的 Coding Plan 适合这种长期运行的编码和 Agent 场景地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 按需选套餐即可。最后提醒一点MCP 工具调用会消耗模型 token尤其是大 PDF 解析后返回的 Markdown 很长再让模型抽取字段时上下文会很大。建议在 Agent 里设置合理的 max tokens或者先用 MinerU 解析落盘再用另一个工作流读 Markdown 做抽取把解析和抽取拆成两步成本和稳定性都更好。