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