1. 为什么零基础也要用 n8n 调 MinerU MCP 做文档处理自动化
如果你手里有一堆 PDF 合同、扫描版论文、带公式的技术手册，想批量转成 Markdown 再抽取字段归档，纯手工复制粘贴基本等于自虐。MinerU 能把这些文档转成结构化 Markdown，支持 OCR、公式和表格识别；n8n 是开源可视化工作流工具，拖几个节点就能把「上传文件 → 解析 → 大模型抽取 → 写盘归档」串成一条流水线。两者通过 MCP（Model Context Protocol）对接后，你不需要写复杂代码，只要在 n8n 里配好 MCP Client 节点，就能让大模型直接调用 MinerU 的解析能力。
这套组合适合谁？适合不想碰 Python 脚本的运营、法务、科研助理，也适合想快速验证文档自动化链路的开发者。我实测下来，最省事的路径是：本地起一个 MinerU MCP Server，n8n 里用 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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如果看到持续的事件流输出（不要按 Ctrl+C，另开终端），说明 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_TIMEOUT=3600000 n8n start3600000 毫秒等于 1 小时，足够处理大部分文档。如果你在 Windows PowerShell 里，用$env:NODES_MCP_TIMEOUT=3600000。
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 Server；MinerU 解析完成后返回 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_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。这样能把「模型本身的问题」和「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/api，Key 有没有多余空格。另外，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_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，对照检查请求头格式。
还有一个隐蔽的坑：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_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，按需选套餐即可。
最后提醒一点：MCP 工具调用会消耗模型 token，尤其是大 PDF 解析后返回的 Markdown 很长，再让模型抽取字段时上下文会很大。建议在 Agent 里设置合理的 max tokens，或者先用 MinerU 解析落盘，再用另一个工作流读 Markdown 做抽取，把解析和抽取拆成两步，成本和稳定性都更好。
