1. 为什么要在本地跑 MinerU MCP Server如果你经常把 PDF 研报、合同、论文丢给 AI 编程助手让它帮你总结、比对、抽公式那你大概率遇到过同一个尴尬模型说我看不到这个文件内容。原因很简单大多数 AI 宿主Claude Desktop、Cursor、Cline本身并不具备文档解析能力它们只能读纯文本。PDF 里的表格、公式、双栏排版直接喂进去就是一团乱码。MinerU MCP Server 解决的就是这个问题。它把 MinerU 的文档解析管线封装成一个符合 MCPModel Context Protocol协议的工具服务暴露parse_documents和get_ocr_languages两个工具方法。任何支持 MCP 的宿主只要注册一次这个 Server就能在对话里直接调用文档解析能力——PDF、Word、PPT、图片都能转成结构化 Markdown表格保留 HTML 结构公式保留 LaTeX 格式。这篇文章面向的是需要把文档解析接入 AI 编程工具的开发者。我会带你走完完整链路本地部署 MinerU MCP Server、配置 Claude Desktop / Cursor / Cline 三类客户端、通过 TaoToken 统一 Key 通道完成鉴权、最后做一次端到端解析验证。全程可复制踩过的坑我也会标出来。先说清楚三个角色的关系不然后面配置容易懵。Host 是宿主比如 Claude Desktop、Cursor、ClineClient 是宿主内建的 MCP 客户端负责发现和调用工具Server 就是我们今天要部署的 MinerU MCP Server。Host 启动 ClientClient 连接 ServerServer 返回工具清单并响应调用。你配置的 JSON 文件本质就是告诉 Client去哪里找这个 Server、用什么鉴权。MinerU MCP Server 支持两种传输模式stdio 和 streamable-http。stdio 模式下宿主会自动拉起一个子进程通过标准输入输出通信适合个人单机开发streamable-http 模式下Server 作为独立 HTTP 服务常驻多个客户端可以共享同一个地址适合团队或需要多宿主复用的场景。两种模式的配置片段我都会给。2. TaoToken 统一 Key 与前置准备在动手配置之前先把鉴权这条线理清楚。MinerU MCP Server 本身需要一个MINERU_API_TOKEN来调用后端解析 API而你的 AI 宿主Claude Desktop / Cursor / Cline在调用模型时又需要另一套 Key。如果每个客户端都单独配一套管理起来会很乱。我的做法是用 TaoToken 作为统一的 API 通道把模型调用的 Key 收敛到一处。TaoToken 的定位是统一的模型 API 接入层官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你可以在控制台里创建 API Key然后在各个客户端里统一填这个 Key 和 Base URL。这样 Claude Desktop、Cursor、Cline 三个宿主用的是同一套凭证轮转的时候只改一处。前置准备清单如下。第一安装 uv这是 Python 包管理器MinerU MCP Server 通过uvx命令拉起。第二准备一个 MinerU API Token不设的话 Server 会以 Flash 模式运行免费但只输出 Markdown 且文件大小有限制适合先跑通链路。第三在 TaoToken 控制台创建一个 API Key后面配置客户端模型通道时用。先验证 uv 是否装好uv --version # 期望输出类似 uv 0.5.x如果没装去 astral.sh 的 uv 文档按系统装一下。Windows 用户建议用 PowerShell 安装脚本装完重开终端让 PATH 生效。然后是 TaoToken 的 Key。登录控制台后进入 API Keys 页面创建复制出来先存好。这个 Key 后面会出现在三个客户端的配置里。注意不要把它硬编码进会提交到 Git 的文件用环境变量引用更安全。MinerU 的 Token 去 mineru.net 申请免费额度够个人用。如果你只是想先验证链路通不通可以先不填 MinerU Token让 Server 跑 Flash 模式等配置全部跑通再换成正式 Token。这里有个容易忽略的点uvx第一次运行mineru-open-mcp时会自动下载依赖包国内网络环境下可能比较慢。建议先手动跑一次让它把包缓存下来uvx mineru-open-mcp --help看到帮助信息输出说明包已经拉下来了后面客户端拉起子进程会快很多。3. 可复制的 MCP Server 与客户端配置这一节是全文的核心所有配置片段都可以直接复制。我按先起 Server再配客户端的顺序来每个片段都标了文件路径。3.1 stdio 模式个人开发推荐stdio 模式不需要手动启动 Server客户端配置好 JSON 后会自动拉起子进程。Claude Desktop 的配置文件路径因系统而异macOS 是~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 是%APPDATA%\Claude\claude_desktop_config.json。完整配置片段如下{ mcpServers: { mineru: { command: uvx, args: [mineru-open-mcp], env: { MINERU_API_TOKEN: your_mineru_api_token_here } } } }如果你同时用 TaoToken 作为模型通道Claude Desktop 的模型配置在设置界面里填 Base URL 和 KeyMCP 配置和模型配置是两套东西不要混在一个文件里。MCP 只管工具模型通道管推理。Cursor 的项目级配置放在项目根目录的.cursor/mcp.json格式和上面一致{ mcpServers: { mineru: { command: uvx, args: [mineru-open-mcp], env: { MINERU_API_TOKEN: your_key_here } } } }Cline 是 VS Code 插件配置入口在 VS Code 设置里搜cline.mcpServers填入同样的 JSON 结构。三件套要写全Base URL、Key、Model ID。Cline 的模型通道配置在插件设置里Base URL 填https://taotoken.net/apiKey 填 TaoToken 控制台创建的 KeyModel ID 按你实际用的模型填。3.2 streamable-http 模式团队共享推荐如果多个宿主需要共用同一个解析服务用 HTTP 模式。先手动启动 ServerMINERU_API_TOKENyour_key mineru-open-mcp --transport streamable-http --port 8001然后客户端指向服务端地址。Claude Desktop 的配置改成{ mcpServers: { mineru: { type: streamableHttp, url: http://127.0.0.1:8001/mcp } } }HTTP 模式下客户端不持有 MinerU TokenToken 配在服务端环境变量里泄漏面小很多。团队场景下一台机器起一个 HTTP Server其他人只填 URL 就行。3.3 配置校验改完 JSON 一定要校验合法性一个多余的逗号就会让整个 MCP 加载失败cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .jq能解析说明 JSON 合法。Windows 用户可以用在线 JSON 校验工具或者装个 jq 的 Windows 版。4. 验证请求与端到端解析结果配置写完接下来验证链路是否真的通了。这一步不能省很多人配完以为好了结果对话里工具根本没注册。Claude Desktop 需要完全退出再重启不是关窗口是退出进程。重启后在对话输入框下方应该能看到一个工具图标展开后能看到parse_documents和get_ocr_languages两个工具。如果没出现先检查 uv 是否在 PATH 里which uv # 应该输出 uv 的完整路径Cursor 不需要重启重新加载窗口即可。在 Composer 或 Chat 面板里工具会自动可用。Cline 同理配置后在对话里就能触发。验证工具注册成功后做一次真实解析。找一个 PDF 文件在对话里写明完整路径请解析这个 PDF 的第 1-3 页/Users/yourname/Downloads/test-report.pdfClaude 会调用parse_documentsMinerU Server 上传文件并解析返回结构化 Markdown。你应该能看到表格以 HTML 格式保留公式以 LaTeX 格式保留。如果返回的是纯文本流、表格结构丢了说明解析模式不对检查 MinerU Token 是否生效。关于文件路径有个坑Claude Desktop 会把拖入的文件沙箱化到临时目录MCP Server 找不到原始路径。所以提示里要写文件的真实绝对路径不要依赖拖拽。验证成功后你可以试试更复杂的场景。比如让它解析一份双栏排版的论文看公式和正文有没有错位。MinerU 的版面分析模型会先识别栏区域再确定阅读方向而不是按 PDF 物理文本流顺序读双栏场景下这个能力很关键。再验证一下 HTTP 模式。手动起 Server 后用 curl 探一下端口curl -s http://127.0.0.1:8001/mcp -X POST -H Content-Type: application/json -d {jsonrpc:2.0,method:tools/list,id:1}能返回工具清单 JSON说明 HTTP Server 正常。然后在客户端里做一次解析确认结果和 stdio 模式一致。5. 本篇常见报错排查配置过程中最容易撞的几个报错我按真实错误信息对照着说。401 Unauthorized。这个通常是 MinerU Token 或 TaoToken Key 填错、过期或者环境变量没传进去。检查MINERU_API_TOKEN是否拼写正确TaoToken 的 Key 是否在控制台被禁用。HTTP 模式下 Token 配在服务端客户端报 401 说明服务端没读到环境变量重启 Server 时确认MINERU_API_TOKENxxx前缀写对了。local proxy failed / connection refused。这个多见于 HTTP 模式客户端填的 URL 端口和 Server 实际监听端口不一致或者 Server 没起来。先curl探端口确认 Server 活着再检查客户端 URL 是不是http://127.0.0.1:8001/mcp路径末尾的/mcp不能少。Error reading choices / 返回空内容。这个一般是模型通道的问题不是 MCP 的问题。检查 TaoToken 的 Base URL 是否填成https://taotoken.net/apiModel ID 是否是通道支持的模型。如果 Base URL 填了带 UTM 的官网地址会 404API 端点不带 UTM。OAuth 相关报错。部分客户端在模型通道鉴权时会走 OAuth 流程如果你用的是 API Key 模式确认客户端设置里选的是 API Key 而不是 OAuth。Codex 的auth.json里如果混了旧的 OAuth 凭证清掉重新填 Key。工具列表为空。MCP 配置 JSON 合法但工具没注册八成是uvx不在 PATH。Claude Desktop 启动时继承的环境变量可能和你终端里不一样用绝对路径填command字段比如/Users/yourname/.local/bin/uvx。大文件超时。MinerU API 对单文件有 200MB / 200 页限制超大文件解析时客户端可能先超时断开。用page_ranges参数拆页或者在客户端配置里调大 timeout。并发下 stdio 卡死。stdio 是一对一管道多个任务并发会排队。切到 streamable-http 模式HTTP Server 能处理并发请求。排查顺序建议先确认 JSON 合法再确认 uv 在 PATH再确认 Token 有效最后确认网络能到 MinerU API。大部分问题出在前两步。6. 把文档解析接进你的日常工作流链路跑通之后真正的价值在于把它接进日常。我自己的用法是研报丢给 Claude Desktop 做摘要和表格提取合同比对在 Cursor 里做批量文档处理用 Cline 配合脚本。三个宿主共用同一套 TaoToken Key切换成本几乎为零。如果你需要长期跑编码和 Agent 任务建议把模型通道切到 Coding Plan额度更稳。验证模型能力的时候用模型对话页面快速试。API Key 的创建和管理都在控制台的 API Keys 页面接入文档在文档中心里面有各客户端的详细配置说明。MinerU MCP Server 的配置本身不复杂复杂的是把鉴权、传输模式、客户端差异这三件事理清楚。理清之后复制配置文件的成本接近于零这就是协议化带来的直接收益。
