1. MinerU MCP Server 源碼部署后PDF 解析鏈路為什么要統(tǒng)一 Key 通道MinerU MCP Server 是把 PDF 解析能力封裝成 MCP 工具的開(kāi)源項(xiàng)目它本身不負(fù)責(zé)大模型推理只負(fù)責(zé)把 PDF 轉(zhuǎn)成 Markdown 這類結(jié)構(gòu)化文本。真正調(diào)用它的是 Claude Code、Cline、Cursor 這類支持 MCP 協(xié)議的客戶端而這些客戶端在解析完文檔后往往還要把結(jié)果交給大模型做總結(jié)、問(wèn)答或代碼生成。問(wèn)題就出在這里MCP 服務(wù)一套配置大模型請(qǐng)求又是另一套配置兩邊的 endpoint 和 Key 各管各的時(shí)間一長(zhǎng)就會(huì)出現(xiàn)「PDF 解析成功了但模型調(diào)用 401」這種割裂感。我試過(guò)把 MinerU MCP Server 的解析結(jié)果直接丟給本地配置的模型通道結(jié)果發(fā)現(xiàn)模型側(cè)的 Base URL 和 Key 散落在好幾個(gè)配置文件里換一次 Key 要改三四個(gè)地方。所以這篇的核心思路是MinerU MCP Server 負(fù)責(zé) PDF 解析模型請(qǐng)求的 endpoint 與 Key 統(tǒng)一收斂到 TaoToken 這一條通道上。這樣你只需要維護(hù)一份 KeyMCP 客戶端和模型調(diào)用都指向同一個(gè)入口排障時(shí)也能快速定位是解析層的問(wèn)題還是模型層的問(wèn)題。適合誰(shuí)看如果你已經(jīng)在本地跑通了 MinerU MCP Server 的源碼部署或者正準(zhǔn)備把 PDF 解析接進(jìn)自己的 Agent 工作流但被多套 Key 管理搞得很煩這篇就是寫給你的。下面會(huì)給出可復(fù)制的 MCP 配置片段、TaoToken 統(tǒng)一 Key 的填寫位置以及一次完整的 PDF 解析調(diào)用驗(yàn)證動(dòng)作目標(biāo)是在本地把 MinerU 解析鏈路和模型通道一起跑通。需要先明確三個(gè)概念避免后面配置時(shí)混淆。MCP 是模型上下文協(xié)議負(fù)責(zé)讓大模型和外部工具之間用標(biāo)準(zhǔn)化方式通信MinerU API 是真正執(zhí)行 PDF 到 Markdown 轉(zhuǎn)換的后端服務(wù)MinerU MCP Server 則是中間層把 MinerU API 的能力包裝成符合 MCP 規(guī)范的接口。大模型通過(guò) MCP 客戶端調(diào)用 MinerU MCP ServerMinerU MCP Server 再去調(diào) MinerU API 完成實(shí)際轉(zhuǎn)換。而模型本身的請(qǐng)求則走 TaoToken 的統(tǒng)一通道。兩條鏈路各司其職但 Key 的管理可以合并到一處。2. TaoToken 前置準(zhǔn)備統(tǒng)一 Key 與 endpoint 的獲取和填寫位置在動(dòng)手改配置之前先把 TaoToken 這邊的準(zhǔn)備工作做完。TaoToken 的作用是給模型請(qǐng)求提供一個(gè)統(tǒng)一的 endpoint 和 Key 通道你不需要在多個(gè)客戶端里分別填不同的模型服務(wù)地址只要把 Base URL 指向 TaoToken 的 API 地址再用同一個(gè) Key 就能調(diào)用背后配置好的模型。對(duì)于 MinerU MCP 這種「解析 模型」混合鏈路來(lái)說(shuō)統(tǒng)一 Key 能省掉大量重復(fù)配置。第一步是拿到 Key。打開(kāi) TaoToken 的控制臺(tái)進(jìn)入 API Keys 頁(yè)面創(chuàng)建一個(gè)新的 Key。創(chuàng)建時(shí)建議給它起一個(gè)能識(shí)別的名字比如mineru-mcp-local方便后面在多個(gè)客戶端里區(qū)分。創(chuàng)建完成后把 Key 復(fù)制出來(lái)注意這個(gè) Key 只會(huì)在創(chuàng)建時(shí)完整顯示一次后面再進(jìn)頁(yè)面就只能看到前綴了。如果你之前已經(jīng)有 Key也可以直接復(fù)用但建議為 MCP 場(chǎng)景單獨(dú)建一個(gè)方便出問(wèn)題時(shí)快速吊銷而不影響其他項(xiàng)目。第二步是確認(rèn) endpoint。TaoToken 的 API 地址是https://taotoken.net/api這個(gè)地址在配置 MCP 客戶端和模型請(qǐng)求時(shí)都會(huì)用到。注意這里不要加多余的路徑后綴很多 401 和 404 就是因?yàn)榘?Base URL 寫成了帶/v1或其他后綴的形式。正確的做法是讓客戶端自己去拼接具體路徑你只填到/api這一層。第三步是確認(rèn)模型 ID。TaoToken 支持多種模型你需要在控制臺(tái)或文檔里確認(rèn)自己要用的模型 ID 是什么比如claude-sonnet-4-20250514這類。這個(gè) ID 在 MCP 客戶端的模型配置里會(huì)用到填錯(cuò)會(huì)導(dǎo)致reading choices之類的報(bào)錯(cuò)。如果你不確定用哪個(gè)可以先在模型對(duì)話頁(yè)面里試一下確認(rèn)能正常返回再寫進(jìn)配置文件。這里要特別說(shuō)明一點(diǎn)MinerU MCP Server 本身不調(diào)用大模型它只負(fù)責(zé) PDF 解析。所以 TaoToken 的 Key 和 endpoint 是配在 MCP 客戶端那一側(cè)的也就是 Claude Code、Cline 或 Cursor 這些工具的模型設(shè)置里。MinerU MCP Server 的.env里填的是 MinerU 自己的 API Key如果用官方 API 的話兩者不要混在一起。很多人第一次配的時(shí)候會(huì)把 TaoToken 的 Key 填進(jìn) MinerU 的MINERU_API_KEY結(jié)果解析請(qǐng)求全部失敗這個(gè)坑要避開(kāi)。如果你用的是 Claude Code 這類工具它的配置通常放在~/.claude/settings.json或項(xiàng)目級(jí)的.claude/settings.json里。Cline 則是在 VSCode 的設(shè)置里找 MCP 和模型配置。Codex 的話會(huì)涉及auth.json。不管哪個(gè)客戶端核心都是三件套Base URL 填https://taotoken.net/apiKey 填你剛創(chuàng)建的那個(gè)Model ID 填你要用的模型。這三樣填對(duì)模型請(qǐng)求就能走通。3. 可復(fù)制配置MinerU MCP Server 與 TaoToken 統(tǒng)一 Key 的完整片段這一節(jié)給出可以直接復(fù)制的配置片段。先處理 MinerU MCP Server 這一側(cè)再處理 MCP 客戶端的模型側(cè)最后把兩邊串起來(lái)。MinerU MCP Server 的配置分源碼模式和包管理模式兩種。源碼模式下進(jìn)入 MinerU-MCP 目錄后創(chuàng)建.env文件內(nèi)容如下# 使用本地 MinerU API USE_LOCAL_APItrue # 本地 MinerU API 地址 LOCAL_MINERU_API_BASEhttp://localhost:8888 # 轉(zhuǎn)換后文件保存路徑 OUTPUT_DIR./downloads如果你用的是 MinerU 官方 API 而不是本地服務(wù)把USE_LOCAL_API改成false并補(bǔ)上官方 API 的 KeyUSE_LOCAL_APIfalse MINERU_API_BASEhttps://mineru.net MINERU_API_KEY你的MinerU官方Key OUTPUT_DIR./downloads注意這里的MINERU_API_KEY是 MinerU 官方服務(wù)的 Key不是 TaoToken 的 Key兩者用途不同。MinerU 的 Key 只用于 PDF 解析TaoToken 的 Key 用于模型請(qǐng)求。接下來(lái)是 MCP 客戶端的配置。以 Cline 為例MCP 服務(wù)器配置通常寫在cline_mcp_settings.json里路徑在 VSCode 的全局存儲(chǔ)目錄下。配置片段如下{ mcpServers: { mineru-mcp: { command: uvx, args: [mineru-mcp], env: { MINERU_API_BASE: https://mineru.net, MINERU_API_KEY: 你的MinerU官方Key, OUTPUT_DIR: ./downloads, USE_LOCAL_API: false, LOCAL_MINERU_API_BASE: http://localhost:8888 } } } }這段配置讓 Cline 通過(guò)uvx自動(dòng)拉起 MinerU MCP Server不需要你手動(dòng)啟動(dòng) SSE 服務(wù)。如果你用的是源碼模式把command改成uvargs改成[run, -m, mineru.cli, --transport, sse]并確保在激活的虛擬環(huán)境里執(zhí)行。然后是模型側(cè)的配置。Cline 的模型設(shè)置里API Provider 選擇 OpenAI Compatible 或 Anthropic 兼容模式Base URL 填https://taotoken.net/apiAPI Key 填 TaoToken 的 KeyModel ID 填你要用的模型。如果你用的是 Claude Code配置寫在settings.json里{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的TaoToken Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }Codex 的話auth.json里需要填OPENAI_BASE_URL和OPENAI_API_KEY同樣指向 TaoToken 的地址和 Key。三件套的核心就是 Base URL、Key、Model ID缺一不可。如果你用的是 CC Switch 來(lái)管理多個(gè) Claude Code 配置可以在 CC Switch 里新增一個(gè)配置項(xiàng)Base URL 填https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填對(duì)應(yīng)模型。這樣切換配置時(shí)不會(huì)影響到其他項(xiàng)目。配置完成后啟動(dòng)順序也有講究。如果用的是本地 MinerU API先啟動(dòng) MinerU 的 web_api 服務(wù)cd /path/to/MinerU/projects/web_api pip install -r requirements.txt python app.py服務(wù)會(huì)在http://localhost:8888啟動(dòng)。然后再啟動(dòng) MCP 客戶端客戶端會(huì)自動(dòng)拉起 MinerU MCP Server。如果用的是 SSE 模式需要手動(dòng)啟動(dòng)cd /path/to/mineru-mcp source .venv/bin/activate uv run -m mineru.cli --transport sse服務(wù)會(huì)在http://localhost:8001啟動(dòng)。stdio 模式則不需要手動(dòng)啟動(dòng)客戶端會(huì)自己管理進(jìn)程。4. 驗(yàn)證請(qǐng)求一次完整的 PDF 解析調(diào)用與成功結(jié)果確認(rèn)配置寫完之后必須做一次完整的驗(yàn)證確認(rèn) PDF 解析鏈路和模型通道都通了。驗(yàn)證分兩步先確認(rèn) MinerU MCP Server 能被客戶端識(shí)別再確認(rèn)模型能通過(guò) TaoToken 正常返回。第一步在 MCP 客戶端里查看工具列表。以 Cline 為例打開(kāi) MCP 服務(wù)器面板應(yīng)該能看到mineru-mcp處于已連接狀態(tài)并且列出了parse_documents和get_ocr_languages兩個(gè)工具。如果顯示未連接先檢查uvx是否在 PATH 里再檢查.env或 JSON 里的環(huán)境變量有沒(méi)有拼錯(cuò)。常見(jiàn)的問(wèn)題是MINERU_API_KEY填成了 TaoToken 的 Key導(dǎo)致 MinerU 側(cè)認(rèn)證失敗。第二步發(fā)一條解析請(qǐng)求。在對(duì)話里輸入請(qǐng)使用 MinerU MCP 將以下 URL 的 PDF 文檔轉(zhuǎn)換為 Markdown 格式https://arxiv.org/pdf/2303.08774.pdf模型會(huì)識(shí)別這是文檔轉(zhuǎn)換任務(wù)調(diào)用parse_documents工具參數(shù)為{file_sources: https://arxiv.org/pdf/2303.08774.pdf}。如果一切正常你會(huì)看到工具調(diào)用過(guò)程然后返回轉(zhuǎn)換后的 Markdown 內(nèi)容開(kāi)頭通常是論文標(biāo)題和摘要部分。第三步確認(rèn)模型請(qǐng)求走的是 TaoToken。這一步容易被忽略。你可以在 TaoToken 的控制臺(tái)里查看調(diào)用日志確認(rèn)剛才的模型請(qǐng)求確實(shí)打到了 TaoToken 的 endpoint 上。如果日志里沒(méi)有記錄說(shuō)明模型請(qǐng)求還在走本地或其他通道需要回去檢查 Base URL 和 Key 的配置。第四步測(cè)試本地文件解析。輸入請(qǐng)使用 MinerU MCP 將本地的 /Users/yourname/sample.pdf 文件轉(zhuǎn)換為 Markdown 格式模型會(huì)調(diào)用parse_documents參數(shù)為{file_sources: /Users/yourname/sample.pdf}。注意這里要用絕對(duì)路徑相對(duì)路徑容易因?yàn)楣ぷ髂夸洸煌也坏轿募?。如果?bào)文件不存在先確認(rèn)路徑拼寫再確認(rèn) MCP Server 進(jìn)程有權(quán)限讀取該文件。第五步測(cè)試 OCR 場(chǎng)景。如果你有掃描版 PDF可以輸入請(qǐng)使用 MinerU MCP 將以下 URL 的掃描版 PDF 轉(zhuǎn)換為 Markdown并啟用 OCRhttps://example.com/scanned.pdf模型會(huì)調(diào)用parse_documents并帶上enable_ocr: true參數(shù)。OCR 處理時(shí)間會(huì)比普通解析長(zhǎng)耐心等待即可。如果超時(shí)參考下一節(jié)的排障方法。驗(yàn)證成功的標(biāo)志有三個(gè)MCP 工具列表里能看到parse_documents解析請(qǐng)求能返回 Markdown 內(nèi)容TaoToken 控制臺(tái)里能看到對(duì)應(yīng)的模型調(diào)用記錄。三個(gè)都滿足說(shuō)明 PDF 解析鏈路和統(tǒng)一 Key 通道都跑通了。5. 本篇常見(jiàn)錯(cuò)排查401、local proxy failed、reading choices 與 OAuth 報(bào)錯(cuò)配置過(guò)程中最容易撞上的就是認(rèn)證類報(bào)錯(cuò)。下面按真實(shí)報(bào)錯(cuò)逐個(gè)拆解。401 Unauthorized。這個(gè)報(bào)錯(cuò)通常出現(xiàn)在模型請(qǐng)求側(cè)說(shuō)明 TaoToken 的 Key 沒(méi)填對(duì)或沒(méi)生效。先檢查 Key 是否完整復(fù)制有沒(méi)有多余空格。再檢查 Base URL 是不是寫成了https://taotoken.net/api/帶尾斜杠有些客戶端會(huì)把尾斜杠拼成雙斜杠導(dǎo)致路徑錯(cuò)誤。如果 Key 和 URL 都沒(méi)問(wèn)題去 TaoToken 控制臺(tái)確認(rèn)這個(gè) Key 是否被吊銷或過(guò)期。還有一種情況是把 MinerU 的 Key 填到了模型配置里兩者搞混了這個(gè)要特別注意。local proxy failed。這個(gè)報(bào)錯(cuò)一般出現(xiàn)在客戶端嘗試連接本地 MCP 服務(wù)時(shí)說(shuō)明 MCP Server 進(jìn)程沒(méi)起來(lái)或者端口不對(duì)。先確認(rèn) MinerU MCP Server 是否在運(yùn)行SSE 模式下檢查http://localhost:8001是否能訪問(wèn)。如果用的是 stdio 模式檢查command和args是否寫對(duì)uvx是否在 PATH 里。Windows 上還要注意路徑分隔符和引號(hào)轉(zhuǎn)義問(wèn)題。reading choices 報(bào)錯(cuò)。這個(gè)通常出現(xiàn)在模型返回階段說(shuō)明請(qǐng)求發(fā)出去了但響應(yīng)格式不對(duì)。常見(jiàn)原因是 Model ID 填錯(cuò)了比如填了一個(gè) TaoToken 不支持的模型名。去 TaoToken 的模型列表里確認(rèn)可用的 Model ID填一個(gè)確定能用的。另一個(gè)原因是客戶端把請(qǐng)求發(fā)到了錯(cuò)誤的 endpoint比如把 Anthropic 格式的請(qǐng)求發(fā)到了 OpenAI 兼容接口上這個(gè)要對(duì)照客戶端的 API Provider 設(shè)置來(lái)排查。OAuth 相關(guān)報(bào)錯(cuò)。如果你用的是 Claude Code 或 Codex 這類帶 OAuth 流程的工具可能會(huì)遇到 OAuth 認(rèn)證失敗。這時(shí)候要確認(rèn)settings.json或auth.json里的 Base URL 和 Key 是否覆蓋了默認(rèn)的 OAuth 配置。有些工具會(huì)優(yōu)先走 OAuth 再走 API Key需要在配置里顯式禁用 OAuth 或把 API Key 模式設(shè)為優(yōu)先。如果報(bào)錯(cuò)信息里提到invalid_grant或token expired說(shuō)明 OAuth token 失效了切到 API Key 模式即可繞過(guò)。MCP error -32001: Request timed out。這個(gè)報(bào)錯(cuò)在處理大型 PDF 時(shí)很常見(jiàn)。MinerU 解析大文檔本身耗時(shí)較長(zhǎng)加上模型側(cè)的超時(shí)設(shè)置很容易觸發(fā)。解決辦法有幾個(gè)把大文檔拆成多個(gè)小文件分批處理改用本地 MinerU API 模式減少網(wǎng)絡(luò)延遲在客戶端設(shè)置里調(diào)大超時(shí)時(shí)間如果支持的話。Cursor 有個(gè)已知問(wèn)題超時(shí)后無(wú)法再次調(diào)用 MCP 服務(wù)需要重啟客戶端才能恢復(fù)。如果反復(fù)超時(shí)優(yōu)先考慮分批處理。文件路徑找不到。parse_documents處理本地文件時(shí)報(bào)找不到文件九成是路徑問(wèn)題。MCP Server 進(jìn)程的工作目錄可能和你想的不一樣所以相對(duì)路徑經(jīng)常失效。統(tǒng)一用絕對(duì)路徑Windows 上注意用正斜杠或雙反斜杠。如果文件在遠(yuǎn)程機(jī)器上先確認(rèn) MCP Server 有權(quán)限訪問(wèn)該路徑。MinerU API 認(rèn)證失敗。如果報(bào)錯(cuò)指向 MinerU 側(cè)檢查MINERU_API_KEY是否是 MinerU 官方申請(qǐng)的 Key而不是 TaoToken 的 Key。如果用本地 API 模式確認(rèn)USE_LOCAL_APItrue且LOCAL_MINERU_API_BASE指向正確的本地地址。本地服務(wù)沒(méi)啟動(dòng)的話解析請(qǐng)求會(huì)直接失敗。排障的核心思路是分層定位先確認(rèn) MCP Server 是否運(yùn)行再確認(rèn) MinerU API 是否可達(dá)最后確認(rèn)模型請(qǐng)求是否走通 TaoToken。每一層都有對(duì)應(yīng)的日志和報(bào)錯(cuò)按層排查比盲目改配置高效得多。6. 把 PDF 解析接進(jìn)日常 Agent 工作流統(tǒng)一 Key 之后的實(shí)用建議鏈路跑通之后真正提升效率的是把它接進(jìn)日常的 Agent 工作流。統(tǒng)一 Key 通道之后你可以在多個(gè)客戶端之間共享同一份 TaoToken 配置不用每個(gè)工具都重新填一遍。比如你在 Cline 里配好了 MinerU MCP 和 TaoToken換到 Claude Code 時(shí)只需要把settings.json里的 Base URL 和 Key 復(fù)制過(guò)去Model ID 按需調(diào)整即可。一個(gè)實(shí)用的做法是把 MinerU MCP 的解析結(jié)果直接喂給模型做后續(xù)處理。比如解析完一篇論文后緊接著讓模型提取關(guān)鍵結(jié)論、生成摘要或翻譯成中文。因?yàn)槟Ｐ驼?qǐng)求走的是 TaoToken 統(tǒng)一通道你不需要在解析和模型調(diào)用之間切換配置整個(gè)流程是連貫的。實(shí)測(cè)下來(lái)這種「解析 處理」的組合在文獻(xiàn)整理、合同審閱、技術(shù)文檔翻譯這些場(chǎng)景里特別省事。對(duì)于需要長(zhǎng)期跑的任務(wù)建議把 MinerU MCP Server 配成 SSE 模式并常駐后臺(tái)這樣多個(gè)客戶端可以共享同一個(gè) MCP 服務(wù)實(shí)例不用每次啟動(dòng)都重新拉起進(jìn)程。SSE 模式下服務(wù)監(jiān)聽(tīng)在http://localhost:8001客戶端配置里填這個(gè)地址即可。stdio 模式適合臨時(shí)用每次調(diào)用都會(huì)新起進(jìn)程啟動(dòng)開(kāi)銷略大。如果你在用 Coding Plan 做長(zhǎng)期編碼或 Agent 任務(wù)可以把 TaoToken 的 Key 和 MinerU MCP 配置一起寫進(jìn)項(xiàng)目級(jí)的配置文件里這樣團(tuán)隊(duì)成員拉下代碼后只需要填自己的 Key 就能跑通。注意不要把 Key 提交到版本庫(kù)用環(huán)境變量或本地配置文件的方式管理。最后提醒一點(diǎn)MinerU MCP Server 的源碼在 GitHub 上持續(xù)更新配置格式可能會(huì)有變化。升級(jí)版本后先對(duì)照官方文檔確認(rèn).env的字段名有沒(méi)有改再重新跑一次驗(yàn)證請(qǐng)求。TaoToken 側(cè)的 Key 和 endpoint 相對(duì)穩(wěn)定一般不需要頻繁調(diào)整。把這兩條鏈路的配置分開(kāi)管理出問(wèn)題時(shí)能快速定位是哪一側(cè)的問(wèn)題比混在一起排查要輕松得多。