1. 為什么零基礎(chǔ)也要用 n8n 調(diào) MinerU MCP 做文檔處理自動(dòng)化如果你手里有一堆 PDF 合同、掃描版論文、帶公式的技術(shù)手冊(cè)想批量轉(zhuǎn)成 Markdown 再抽取字段歸檔純手工復(fù)制粘貼基本等于自虐。MinerU 能把這些文檔轉(zhuǎn)成結(jié)構(gòu)化 Markdown支持 OCR、公式和表格識(shí)別n8n 是開(kāi)源可視化工作流工具拖幾個(gè)節(jié)點(diǎn)就能把「上傳文件 → 解析 → 大模型抽取 → 寫盤歸檔」串成一條流水線。兩者通過(guò) MCPModel Context Protocol對(duì)接后你不需要寫復(fù)雜代碼只要在 n8n 里配好 MCP Client 節(jié)點(diǎn)就能讓大模型直接調(diào)用 MinerU 的解析能力。這套組合適合誰(shuí)適合不想碰 Python 腳本的運(yùn)營(yíng)、法務(wù)、科研助理也適合想快速驗(yàn)證文檔自動(dòng)化鏈路的開(kāi)發(fā)者。我實(shí)測(cè)下來(lái)最省事的路徑是本地起一個(gè) MinerU MCP Servern8n 里用 MCP Client 節(jié)點(diǎn)連上它再掛一個(gè)大模型對(duì)話節(jié)點(diǎn)做觸發(fā)和字段抽取最后用 Write Files 節(jié)點(diǎn)落盤。整條鏈路跑通后你丟一個(gè) PDF 進(jìn)去出來(lái)的就是 Markdown 加結(jié)構(gòu)化 JSON。這里有個(gè)關(guān)鍵點(diǎn)n8n 本身不直接解析 PDF它負(fù)責(zé)編排MinerU MCP 負(fù)責(zé)真正的解析和 OCR大模型負(fù)責(zé)理解你的自然語(yǔ)言指令比如「把這份合同里的甲方、金額、簽署日期抽出來(lái)」。三者分工明確你只需要把連接參數(shù)填對(duì)。為了讓大模型調(diào)用更穩(wěn)定我建議用 TaoToken 作為模型接入層。它的 API 地址是 https://taotoken.net/api兼容 OpenAI 格式n8n 的 OpenAI 憑證里把 Base URL 填成這個(gè)就行。這樣你既可以用 GPT-4o-mini 這類模型做對(duì)話觸發(fā)也能在后續(xù)擴(kuò)展里換成其他模型不用改工作流結(jié)構(gòu)。TaoToken 官網(wǎng)是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注冊(cè)后到 API Keys 頁(yè)面生成密鑰即可。2. 前置準(zhǔn)備MinerU MCP Server 與 n8n 環(huán)境搭建在 n8n 里連 MCP 之前你得先把 MinerU MCP Server 跑起來(lái)。這個(gè) Server 是一個(gè)本地服務(wù)默認(rèn)監(jiān)聽(tīng) 8000 端口提供 SSE 接口給 n8n 調(diào)用。安裝方式推薦用 uv比 pip 快且依賴隔離干凈。如果你還沒(méi)裝 uv先執(zhí)行pip install uv uv --version然后拉取 MinerU MCP Server 的源碼并啟動(dòng)。假設(shè)你已經(jīng)把源碼放到本地目錄進(jìn)入該目錄后執(zhí)行uv run mineru-mcp-server --host 0.0.0.0 --port 8000啟動(dòng)成功后終端會(huì)提示 SSE 端點(diǎn)通常是http://localhost:8000/sse。你可以先用 curl 驗(yàn)證一下服務(wù)是否活著curl -N http://localhost:8000/sse如果看到持續(xù)的事件流輸出不要按 CtrlC另開(kāi)終端說(shuō)明 MCP Server 正常。注意這個(gè)服務(wù)需要能訪問(wèn) MinerU 的解析能力所以你的 MinerU API Key 要提前配好通常通過(guò)環(huán)境變量傳入比如MINERU_API_KEY你的key。接下來(lái)裝 n8n。Node.js 14 是硬性要求建議用 18 或 20。全局安裝npm install n8n -g n8n startn8n 默認(rèn)在http://localhost:5678啟動(dòng)。第一次打開(kāi)會(huì)讓你設(shè)置管理員賬號(hào)隨便填一個(gè)你能記住的郵箱和密碼。進(jìn)入后左側(cè)菜單點(diǎn) Workflows準(zhǔn)備創(chuàng)建新工作流。這里有個(gè)容易踩的坑n8n 和 MinerU MCP Server 如果不在同一臺(tái)機(jī)器localhost要換成實(shí)際 IP如果都在本機(jī)但 n8n 跑在 Docker 里那localhost指向的是容器內(nèi)部得用host.docker.internal或者宿主機(jī)的局域網(wǎng) IP。我試過(guò)在 Docker 里直接填 localhost結(jié)果一直連不上換成宿主 IP 才通。另外MCP 調(diào)用可能比較慢尤其是大 PDF 帶 OCR 的時(shí)候。n8n 默認(rèn)的 MCP 超時(shí)時(shí)間偏短建議在啟動(dòng) n8n 前設(shè)置環(huán)境變量export NODES_MCP_TIMEOUT3600000 n8n start3600000 毫秒等于 1 小時(shí)足夠處理大部分文檔。如果你在 Windows PowerShell 里用$env:NODES_MCP_TIMEOUT3600000。3. 可復(fù)制配置n8n 工作流節(jié)點(diǎn)與 MCP 連接參數(shù)現(xiàn)在進(jìn)入核心部分。打開(kāi) n8n點(diǎn)右上角 Create Workflow你會(huì)看到一個(gè)空白畫布。我們需要依次添加這幾個(gè)節(jié)點(diǎn)Chat Trigger對(duì)話觸發(fā)、AI Agent大模型代理、MCP Client Tool連接 MinerU MCP、Write Files from Disk落盤歸檔。先配大模型憑證。點(diǎn)左側(cè) Credentials → Add Credential → 選 OpenAI。在 API Key 里填你在 TaoToken 生成的密鑰Base URL 填https://taotoken.net/api。保存后回到畫布。然后添加 AI Agent 節(jié)點(diǎn)。在 Agent 的 Model 里選剛才的 OpenAI 憑證Model ID 填gpt-4o-mini或者你賬號(hào)里可用的其他模型。Agent 的 System Prompt 可以寫你是一個(gè)文檔處理助手。當(dāng)用戶上傳文件時(shí)調(diào)用 MinerU MCP 的 parse_documents 工具解析文件然后根據(jù)用戶指令抽取字段并以 JSON 返回。接著添加 MCP Client Tool 節(jié)點(diǎn)把它連到 AI Agent 的 Tool 接口。在 MCP Client 配置里SSE Endpoint 填http://localhost:8000/sse如果你改了 MinerU MCP Server 的端口或 IP這里同步改。保存后n8n 會(huì)自動(dòng)拉取該 MCP Server 暴露的工具列表你應(yīng)該能看到parse_documents之類的工具名。再添加 Write Files from Disk 節(jié)點(diǎn)用于把解析結(jié)果寫到本地。File Path 填一個(gè)絕對(duì)路徑比如/Users/yourname/mineru_output/{{ $now.toFormat(yyyyMMdd_HHmmss) }}.mdWindows 下寫成D:\\mineru_output\\{{ $now.toFormat(yyyyMMdd_HHmmss) }}.md。注意路徑里的反斜杠要雙寫或者直接用正斜杠n8n 在 Windows 上也能識(shí)別正斜杠。最后把 Chat Trigger 連到 AI Agent 的輸入AI Agent 的輸出連到 Write Files。整個(gè)工作流的 JSON 結(jié)構(gòu)大致如下你可以直接復(fù)制到 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}]] } } }導(dǎo)入后記得把 Write Files 的路徑改成你自己的MCP Client 的 endpoint 也確認(rèn)一下。如果你用的是 TaoToken 的 Coding Plan 做長(zhǎng)期編碼任務(wù)可以把模型換成更適合代碼和結(jié)構(gòu)化輸出的型號(hào)Base URL 和 Key 不變。4. 端到端驗(yàn)證上傳 PDF 看 Markdown 與歸檔結(jié)果配置保存后點(diǎn)畫布下方的 Open Chat 按鈕會(huì)彈出一個(gè)對(duì)話窗口。在窗口里點(diǎn)回形針圖標(biāo)上傳一個(gè) PDF比如一份帶表格的發(fā)票或者論文首頁(yè)。然后輸入指令請(qǐng)解析這個(gè)文件把正文轉(zhuǎn)成 Markdown并抽取標(biāo)題、作者、日期三個(gè)字段以 JSON 返回。點(diǎn)發(fā)送。你會(huì)看到 AI Agent 開(kāi)始工作它先調(diào)用 MCP Client 的parse_documents工具把文件傳給 MinerU MCP ServerMinerU 解析完成后返回 Markdown 文本大模型再根據(jù)你的指令抽取字段。整個(gè)過(guò)程在對(duì)話窗口里能看到工具調(diào)用日志。如果一切正常Write Files 節(jié)點(diǎn)會(huì)把結(jié)果寫到指定路徑。打開(kāi)那個(gè)文件你應(yīng)該能看到類似這樣的內(nèi)容# 文檔標(biāo)題 作者張三 日期2024-05-20 ## 正文 這里是 MinerU 解析出來(lái)的 Markdown 正文表格和公式都保留為 Markdown 格式。同時(shí)對(duì)話窗口里會(huì)返回 JSON{ title: 文檔標(biāo)題, author: 張三, date: 2024-05-20 }這說(shuō)明整條鏈路跑通了。你可以再試一個(gè)掃描版 PDF驗(yàn)證 OCR 是否生效。如果 MinerU 返回的 Markdown 里文字正確說(shuō)明 OCR 也正常。驗(yàn)證模型對(duì)話是否穩(wěn)定可以到 TaoToken 的模型對(duì)話頁(yè)面單獨(dú)測(cè)一下同一個(gè)模型地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。這樣能把「模型本身的問(wèn)題」和「n8n 工作流的問(wèn)題」分開(kāi)排查。批量歸檔的場(chǎng)景你可以把 Chat Trigger 換成 Webhook 或者 Schedule Trigger配合一個(gè)循環(huán)節(jié)點(diǎn)遍歷文件夾里的所有 PDF。不過(guò)零基礎(chǔ)階段先把單文件跑通再擴(kuò)展批量否則出錯(cuò)時(shí)很難定位是哪個(gè)環(huán)節(jié)的問(wèn)題。5. 常見(jiàn)報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuth第一個(gè)高頻報(bào)錯(cuò)是 401 Unauthorized。如果你在 n8n 的 OpenAI 憑證里填了 TaoToken 的 Key 但沒(méi)改 Base URL請(qǐng)求會(huì)打到 OpenAI 官方自然 401。檢查 Credentials 里的 Base URL 是不是https://taotoken.net/apiKey 有沒(méi)有多余空格。另外TaoToken 的 Key 是在 API Keys 頁(yè)面生成的別把登錄密碼當(dāng) Key 填進(jìn)去。第二個(gè)是local proxy failed或連接被拒絕。這通常是 n8n 連不上 MinerU MCP Server。先確認(rèn) MCP Server 還在運(yùn)行終端沒(méi)關(guān)。然后確認(rèn) endpoint 寫的是/sse結(jié)尾不是/mcp或根路徑。如果 n8n 在 Docker 里把localhost換成host.docker.internal。防火墻也可能攔Windows 上檢查一下 8000 端口是否允許入站。第三個(gè)是reading choices相關(guān)報(bào)錯(cuò)比如Cannot read properties of undefined (reading choices)。這多半是模型返回格式不符合預(yù)期常見(jiàn)原因是 Base URL 填錯(cuò)導(dǎo)致返回了 HTML 錯(cuò)誤頁(yè)或者模型 ID 寫錯(cuò)。檢查 Model ID 是否在你賬號(hào)的可用列表里TaoToken 的模型列表可以在控制臺(tái)看到。另外如果 Agent 的 System Prompt 太復(fù)雜模型可能返回非 JSON也會(huì)觸發(fā)解析錯(cuò)誤先把 Prompt 簡(jiǎn)化再試。第四個(gè)是 OAuth 相關(guān)報(bào)錯(cuò)。n8n 某些節(jié)點(diǎn)會(huì)走 OAuth 流程但 MCP Client 和 OpenAI 憑證都不需要 OAuth。如果你看到 OAuth 報(bào)錯(cuò)大概率是誤點(diǎn)了其他憑證類型刪掉重新建一個(gè) OpenAI 類型的憑證即可。TaoToken 的接入文檔里有各語(yǔ)言的調(diào)用示例地址是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 對(duì)照檢查請(qǐng)求頭格式。還有一個(gè)隱蔽的坑MCP 超時(shí)。如果 PDF 很大n8n 可能在 MCP 返回前就斷了。確認(rèn)啟動(dòng) n8n 前設(shè)置了NODES_MCP_TIMEOUT并且值足夠大。如果還是超時(shí)把 PDF 拆小再試或者檢查 MinerU MCP Server 那邊的日志有沒(méi)有報(bào)錯(cuò)。6. 把鏈路用起來(lái)從單文件到批量歸檔的下一步單文件跑通后你可以把工作流改成批量模式。具體做法加一個(gè) Read Files from Disk 節(jié)點(diǎn)讀取文件夾接一個(gè) Loop Over Items 節(jié)點(diǎn)把每個(gè)文件依次傳給 AI Agent。Write Files 的路徑里用{{ $itemIndex }}或者文件名變量避免覆蓋。如果你想讓整個(gè)系統(tǒng)長(zhǎng)期跑在服務(wù)器上n8n 可以用 Docker 部署MinerU MCP Server 也做成 systemd 服務(wù)或者 Docker 容器。TaoToken 的 Coding Plan 適合這種長(zhǎng)期運(yùn)行的編碼和 Agent 場(chǎng)景地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 按需選套餐即可。最后提醒一點(diǎn)MCP 工具調(diào)用會(huì)消耗模型 token尤其是大 PDF 解析后返回的 Markdown 很長(zhǎng)再讓模型抽取字段時(shí)上下文會(huì)很大。建議在 Agent 里設(shè)置合理的 max tokens或者先用 MinerU 解析落盤再用另一個(gè)工作流讀 Markdown 做抽取把解析和抽取拆成兩步成本和穩(wěn)定性都更好。