Mineru

mineru-mcp

用于 MinerU 文档解析 API 的 MCP 服务和 mineru-cloud CLI，支持完整保留产物、持久化操作和可移植的 PDF 包。

此检出版本中的持久化操作和文档包尚未发布。已发布的 [email protected] 不包含这些功能；npm 用户需要等待包含这些更改的版本发布。

功能

• VLM 模型 — 使用视觉语言模型解析文档
• Pipeline 模型 — 使用 pipeline 模型解析文档
• 本地文件上传 — 上传磁盘上的文件进行批量解析
• 批量处理 — 在一个请求中提交多份文档
• 下载并重命名 — 使用原始文件名提取 Markdown
• 页面范围 — 仅提取指定页面
• 长文档 — mineru_parse_long 提交按页面范围切分的片段，mineru_merge_slices 拼接这些片段
• CLI 对应工具 — mineru-cloud 可在命令行中调用相同的工具
• 语言和 OCR 选项 — 选择语言，并为 pipeline 模型启用 OCR

工具

工具	描述
mineru_parse	解析文档 URL
mineru_status	检查任务进度并获取下载 URL
mineru_batch	解析多个 URL
mineru_batch_status	分页获取批处理结果
mineru_upload_batch	上传本地文件进行批量解析
mineru_download_results	保留完整归档、列出所有成员，并创建带有名称的兼容副本
mineru_parse_long	将长文档作为多个页面范围片段的批次提交
mineru_merge_slices	拼接可用的 Markdown，并保留不可变的片段归档，明确标注未知的页面来源
mineru_capabilities	读取本地已知能力；显式刷新时执行发现
mineru_submit	使用持久化本地日志提交，并防止重复请求
mineru_operation_status	读取已记录的操作；显式刷新时检查远程状态
mineru_resume	继续安全的已记录检查点
mineru_cancel	停止本地处理；不支持远程取消
mineru_bundle	验证并返回某个操作保留的文档包

安装

新安装请使用 Node.js 24。为保持兼容，仍支持 Node.js 18 及更高版本。云端命令需要 MinerU API 密钥；离线创建文档包无需凭据。

本地输出保留、文档包和持久化操作需要 macOS 或 Linux。这些路径使用绑定到目录的文件系统操作，在 Windows 上会安全失败；下方的 Windows 客户端配置并不意味着支持本地保留。

CLI 安装（单行命令）

# Claude Code
claude mcp add mineru-mcp -e MINERU_API_KEY=your-api-key -- npx -y mineru-mcp

# Codex CLI (OpenAI)
codex mcp add mineru --env MINERU_API_KEY=your-api-key -- npx -y mineru-mcp

# Gemini CLI (Google)
gemini mcp add -e MINERU_API_KEY=your-api-key mineru npx -y mineru-mcp

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

OS	配置路径
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mineru": {
      "command": "npx",
      "args": ["-y", "mineru-mcp"],
      "env": {
        "MINERU_API_KEY": "your-api-key"
      }
    }
  }
}

VS Code

添加到 .vscode/mcp.json（工作区），或打开命令面板 > MCP: Open User Configuration（全局）：

{
  "servers": {
    "mineru": {
      "command": "npx",
      "args": ["-y", "mineru-mcp"],
      "env": {
        "MINERU_API_KEY": "your-api-key"
      }
    }
  }
}

注意：VS Code 使用 "servers" 作为顶层键，而不是 "mcpServers"。其他 VS Code 分支版本（Trae、Void、PearAI 等）通常也使用相同格式。

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

{
  "mcpServers": {
    "mineru": {
      "command": "npx",
      "args": ["-y", "mineru-mcp"],
      "env": {
        "MINERU_API_KEY": "your-api-key"
      }
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json（Windows：%USERPROFILE%\.codeium\windsurf\mcp_config.json）：

{
  "mcpServers": {
    "mineru": {
      "command": "npx",
      "args": ["-y", "mineru-mcp"],
      "env": {
        "MINERU_API_KEY": "your-api-key"
      }
    }
  }
}

Cline

在 Cline 面板中打开 MCP Servers 图标 > Configure > Advanced MCP Settings，然后添加：

{
  "mcpServers": {
    "mineru": {
      "command": "npx",
      "args": ["-y", "mineru-mcp"],
      "env": {
        "MINERU_API_KEY": "your-api-key"
      }
    }
  }
}

Cherry Studio

在 Settings > MCP Servers > Add Server 中，将 Type 设为 STDIO，Command 设为 npx，Args 设为 -y mineru-mcp，并添加环境变量 MINERU_API_KEY。或者在 JSON/Code 模式中粘贴：

{
  "mineru": {
    "name": "MinerU",
    "command": "npx",
    "args": ["-y", "mineru-mcp"],
    "env": {
      "MINERU_API_KEY": "your-api-key"
    },
    "isActive": true
  }
}

Witsy

在 Settings > MCP Servers 中添加新服务，将 Type 设为 stdio，Command 设为 npx，Args 设为 -y mineru-mcp，并将环境变量 MINERU_API_KEY 设为你的 API 密钥。

Codex CLI（TOML 配置）

也可以直接编辑 ~/.codex/config.toml：

[mcp_servers.mineru]
command = "npx"
args = ["-y", "mineru-mcp"]

[mcp_servers.mineru.env]
MINERU_API_KEY = "your-api-key"

Gemini CLI（JSON 配置）

也可以直接编辑 ~/.gemini/settings.json：

{
  "mcpServers": {
    "mineru": {
      "command": "npx",
      "args": ["-y", "mineru-mcp"],
      "env": {
        "MINERU_API_KEY": "your-api-key"
      }
    }
  }
}

Windows

在 Windows 上，npx 需要 shell 包装器。将 "command": "npx" 替换为：

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "mineru-mcp"],
  "env": {
    "MINERU_API_KEY": "your-api-key"
  }
}

Windows 上的 CLI 工具：

claude mcp add mineru-mcp -e MINERU_API_KEY=your-api-key -- cmd /c npx -y mineru-mcp
codex mcp add mineru --env MINERU_API_KEY=your-api-key -- cmd /c npx -y mineru-mcp

ChatGPT

ChatGPT 仅支持通过 HTTPS 连接远程 MCP 服务，不直接支持此类本地 stdio 服务。你需要将其部署在公开 URL 后，并使用 HTTP 传输。

CLI：mineru-cloud

每个工具也都是一个 shell 命令——CLI 通过内存传输在进程内运行 MCP 服务，因此两者不会出现偏差。使用相同的环境变量（MINERU_API_KEY、MINERU_BASE_URL、MINERU_DEFAULT_MODEL）。

mineru-cloud list                                    # commands + options (from the tool schemas)
mineru-cloud parse --url https://arxiv.org/pdf/2303.08774 --pages 1-10
mineru-cloud status --task-id <id> --wait            # --wait polls every 10s until done/failed
mineru-cloud batch --urls '["https://…/a.pdf","https://…/b.pdf"]'
mineru-cloud download-results --batch-id <id> --output-dir ./papers --wait

# Long document: slice, then stitch
mineru-cloud parse-long --url https://…/book.pdf --total-pages 520 --name book
mineru-cloud merge-slices --batch-id <id> --output-dir ./books --wait

选项与工具参数相对应，并将 _ 替换为 -（--total-pages、--output-dir）；数字、true/false 和 JSON 数组会自动转换类型。安装：bun add -g mineru-mcp（或 npm i -g）。

离线制品包

使用现有的服务提供方 ZIP 文件和原始 PDF，创建可移植的 Scholia v1.0.1 制品包。此命令离线运行，无需 API 密钥：

mineru-cloud bundle --source /absolute/source.pdf --archive /absolute/result.zip \
  --output /absolute/bundles --json

命令会返回 bundle_dir，即一个不可变目录，其中包含 bundle.json、原始 PDF 和字节完全相同的 ZIP 文件。移动整个目录即可进行导入。重复输入会验证现有字节，并返回相同的制品包。可选的 --batch-id 和 --model 会记录调用方提供的元数据。--binding caller_asserted 会记录经限定的关联；默认值为 unknown。这两种选择都无法证明服务提供方解析的正是这些 PDF 字节。命令不会根据文件名推断页面覆盖范围、请求的选项或服务提供方版本。

此制品包仅接受 PDF 源文件。现有的非 PDF 云端命令仍可使用，并会生成诊断清单。不安全的归档文件会保留在隔离区，不纳入可导入的制品包。ZIP64、加密归档、特殊文件、含义不明确的旧式文件名编码，以及不安全或冲突的路径都会被拒绝。

完整下载与结构化状态

download-results 会将每个 ZIP 保存在 {name}/archives/<sha256>.zip，并写入一个涵盖所有成员（包括未知格式）的 inventory.json。如果选择结果明确无歧义，还会创建旧版 {name}.md、{name}_content.json 和图像副本。Markdown 文件缺失或含义不明确时，不会丢弃归档文件。不使用 shell unzip 可执行文件。清单会增量计算解压后字节的哈希；所选兼容副本的大小上限则单独设为 64 MiB。

生命周期命令可使用 --json 获取结构化的操作 ID、规范化状态、是否可轮询、计数和错误。--wait 会在整个批次中使用类型化状态，包括当前显示页面之外的条目。它每 10 秒轮询一次，最长持续 30 分钟。某个条目失败不会隐藏其他待处理条目。未知的服务提供方状态会明确显示。失败时退出状态为 1，部分结果或未知结果时为 2。现有的 8 个 MCP 工具名称及其 CLI 命令仍可使用。

切片合并会将每个归档文件保存在带哈希标识的目录中。后续合并后，先前的图像链接仍然有效。合并后的内容 JSON 是包含归档引用的切片收据，而非带有假定页面偏移量的扁平数组。Markdown 缺失或切片失败时会明确返回部分结果；否则，覆盖范围和原始 PDF 页面来源仍然未知。

持久化独立操作

另外 6 个命令与 MCP 共用实现：

mineru-cloud capabilities --api v4 --json
mineru-cloud submit --file /absolute/source.pdf --api v4 --model vlm --output-dir /absolute/results --json
mineru-cloud operation-status --operation-id ID --json
mineru-cloud resume --operation-id ID --wait --wait-timeout-seconds 1800 --json
mineru-cloud cancel --operation-id ID --json
mineru-cloud bundle --operation-id ID --json

MINERU_STATE_DIR 用于选择日志根目录；默认值为 ~/.local/share/mineru-cloud。请保留该目录以便恢复。日志会保留源字节、请求指纹、远程 ID、已完成输出的哈希值 以及阶段检查点。凭据和签名 URL 仅保存在进程内存中。 完全重复的提交会加入已记录的操作。分配 ID 或作业 ID 丢失时，需要进行核对，且绝不会触发自动重新提交。 如果某次含糊的 V4 上传已保存批次 ID，则会通过轮询该批次继续操作。 V1 会先检查已知上传，再继续处理结果不确定的完成操作。

同一时间只有一个进程持有写入锁。可通过检查所有者令牌回收普通的死进程锁。若锁恢复步骤中断或 PID 被重用，则会安全失败并返回明确的繁忙／恢复错误。此文件系统日志与 Scholia 的 SQLite 租约和预留系统相互独立；它不提供 Scholia 的工作进程调度或维护保证。

operation-status 默认在本地读取，除非提供 --refresh。resume 会继续安全的检查点。最终定稿会使用已保存的输出，而不会联系提供方。本地取消不会取消远程处理，也不会移除已上传的数据。远程取消和自动关联丢失的 ID 仍不受支持。 已完成的包会保留归档及所有独立输出，包括未知格式。提供方传输完成并不代表 PDF 的所有页面均已覆盖。

V4 持久化 submit --pages 1-2,5 接受正整数页码和包含端点的范围。 请求大小上限为 16 KiB，逗号分隔的区间最多为 1,024 个；零、降序范围以及超出 JavaScript 安全整数范围的数字，会在获取源文件或调用提供方之前导致失败。原始文本会保留在操作标识和提供方选项中。新包会记录排序并合并后的请求区间，且这些区间的覆盖情况均为未知。此意图无法确定已完成或缺失的页面、页面映射或整个文档的覆盖情况。

对较早的范围操作进行完全相同的重放时，会保留其原始包字节，包括未知的请求范围。后续验证通过的输出恢复操作，可以发布一个包含规范化范围意图和原始前驱哈希值的后继包。新范围包使用单独的写入者标识；若目标地址已被冲突内容占用或缺少已记录的包，则会安全失败，而不会改写较早的回执。 超出当前准入范围的旧选择器，只能重放经验证的现有旧版回执。它们不能发布新包或增强现有包，也不能授权提供方操作。

当经过有限次数的下载尝试后仍有一个输出无法获取时，操作会发布一个部分包，其中包含已验证成功的输出和带类型的失败详情。bundle --operation-id ID 可返回这些保留的证据。之后显式执行 resume，可以从同一操作中恢复缺失的输出并发布后继包；较早的包保持不可变。部分结果并不意味着可以再次提交文档。

新的操作命令会在 CLI JSON 和 MCP structuredContent 中使用结构化 Result 封装，同时保留现有的扁平字段以兼容旧版。其 CLI 退出码为：ok 时为 0，partial 或 error 时为 1，参数无效时为 2。原有八条命令仍保留历史退出码：error 为 1，partial 为 2。离线 bundle --source ... --archive ... 也保留现有的已创建／已存在回执格式。请检查 status、state 和恢复详情，而不要将非零退出码理解为允许重新提交。

进程重启测试会在实际的源文件、提交意图、输出保留和最终定稿检查点终止工作进程。可安全接管首次写入日志之前创建且已验证的源文件孤儿；远程提交结果不确定时则不能接管。源文件／输出文件的写入会先同步，再记录对应的日志引用。这些测试验证的是有界的进程崩溃行为，并不构成对断电或网络文件系统的普遍持久性保证。 现代 V1 适配器使用 uploads、parse/jobs 和 files/{id}/content。 它不使用旧版 agent/parse API。显式刷新能力时会查询 health 和独立的 tiers 端点。没有将任何 V4 模型映射到 V1 层级。 V1 不支持范围解析。托管 V1 执行默认仍处于禁用状态，直到完成针对特定端点的验证；可以通过测试夹具注入适配器。

新的网络调用要求使用公开的 HTTPS 地址。DNS 解析结果会在连接时检查并固定；重定向会重新验证，且不会携带 API 授权信息。 传输 URL 仅会接收显式提供的请求头。私有／自托管端点需要单独实现信任策略，此处未启用。 新的 submit 目前仅接受 PDF；原有的 8 个命令仍支持非 PDF 文件。 在这个独立里程碑中，没有账户配额预留、自动调度器，也没有用于关联不确定操作的操作员界面。

官方协议参考资料包括固定版本的 V1 指南、 固定版本的示例 和固定版本的 API 服务架构。 当前指南已于 2026 年 9 月 30 日核查。所有新增执行行为均已通过测试夹具测试；不声称已进行在线服务商验证、版本升级或发布。

配置

环境变量	默认值	描述
MINERU_API_KEY	（必填）	你的 MinerU API Bearer 令牌
MINERU_BASE_URL	https://mineru.net/api/v4	API 基础 URL
MINERU_DEFAULT_MODEL	pipeline	默认模型：pipeline 或 vlm

在 mineru.net 获取 API 密钥

用法

解析单个 URL

mineru_parse({
  url: "https://example.com/document.pdf",
  model: "vlm",        // optional: "pipeline" (default) or "vlm"
  pages: "1-10,15",    // optional: page ranges
  ocr: true,           // optional: enable OCR (pipeline only)
  formula: true,       // optional: formula recognition
  table: true,         // optional: table recognition
  language: "en",      // optional: language code
  formats: ["html"]    // optional: extra export formats
})

检查任务进度

mineru_status({
  task_id: "abc-123",
  format: "concise"    // optional: "concise" (default) or "detailed"
})

精简输出：done | abc-123 | https://cdn-mineru.../result.zip

批量解析 URL

mineru_batch({
  urls: ["https://example.com/doc1.pdf", "https://example.com/doc2.pdf"],
  model: "vlm"
})

检查批次进度

mineru_batch_status({
  batch_id: "batch-123",
  limit: 10,           // optional: max results (default: 10)
  offset: 0,           // optional: skip first N results
  format: "concise"    // optional: "concise" or "detailed"
})

上传本地文件

mineru_upload_batch({
  directory: "/path/to/pdfs",  // scan directory for supported files
  // OR
  files: ["/path/to/doc1.pdf", "/path/to/doc2.pdf"],  // explicit file list
  model: "vlm",        // optional
  formula: true,       // optional
  table: true,         // optional
  language: "en",      // optional
  formats: ["html"]    // optional
})

返回用于跟踪的 batch_id。每个文件的原始名称都会通过 data_id 保留（空格会变为下划线）。

将结果下载为 Markdown

mineru_download_results({
  batch_id: "batch-123",       // from mineru_upload_batch or mineru_batch
  output_dir: "/path/to/output",
  overwrite: false             // optional: overwrite existing files
})

输出文件名由 data_id 派生（例如 my_paper_title.md）。原始文件名中的空格会变为下划线。

典型的本地文件工作流

mineru_upload_batch → mineru_batch_status (poll) → mineru_download_results

支持的格式

• PDF、DOC、DOCX、PPT、PPTX
• PNG、JPG、JPEG

本地限制与服务商依据

旧版批处理命令最多接受 200 个项目；旧版本地上传会拒绝超过 200 MiB 的文件。parse-long 会将每个请求切片限制为 200 页。这些是当前实现中的限制，并不代表已核实服务商账户当前的限额、配额、队列优先级或支持的套餐。获准使用云端任务时，请另行核查这些信息。此代码库的合成测试无法衡量托管解析的准确率、速度或语言覆盖范围。

版本 1.1.6

通过保留 MCP SDK 1.29.x 及其兼容 Node.js 18 的 Hono 适配器，为全新安装恢复 Node.js 18 HTTP 兼容性。SDK 1.30 允许使用要求 Node.js 20 的适配器。版本 1.1.5 通过了锁定依赖检查，但已发布软件包检查发现全新安装时 HTTP 初始化失败。CI 现在会在不使用仓库锁文件的情况下安装打包后的软件包，并在 Node.js 18 上测试两种传输方式。SDK 兼容性限制是有意设置的；采用更新的 SDK 前，应先通过此使用方安装门禁重新评估。

版本 1.1.5

维护版本：审计依赖更新、兼容 Express 5 和 Zod 4，并为两种传输方式补充回归测试。MCP 握手和 HTTP 启动消息现在会报告软件包版本，而不再显示过时的 1.0.2。工具输入和文档处理行为保持不变。

开发

请阅读 AGENTS.md，了解规范的贡献者交接说明、任务权限、恢复不变量，以及配套的 Scholia fixture/集成检查。

开发时请使用 Bun 1.4.2 和推荐的 Node.js 24 运行时：

bun install --frozen-lockfile
bun audit
bun run build
bun run test
bun run test:package

测试使用合成 fixture 和本地 MinerU API 模拟对象。测试会验证构建后的 stdio 和 HTTP 服务、持久化操作恢复、精确保留产物、捆绑包身份，以及文件系统路径包含关系，不需要真实凭据或调用服务提供商。临时 fixture 在 macOS 和 Linux 上使用规范的系统临时目录。这些检查无法证明对实时服务提供商的解析准确性。

对于向 main 提交的 PR、版本标签推送和手动注册表恢复操作，CI 会审核依赖项、构建项目，并在 macOS 和 Linux 上运行完整测试套件。每个平台还会安装一个全新打包的程序包（不使用仓库锁文件），并在 Node.js 18 上测试。此使用者安装门禁确保兼容 Node 18 的目标。Dependabot 会同时更新 Bun 清单和锁文件。向 main 的常规推送不会触发此工作流。

发布

获得明确的发布授权后，更新 package.json、server.json 中的顶层版本及其对应的 npm 程序包版本，完成上述检查并合并，然后推送匹配的 vX.Y.Z 标签。发布前，CI 要求标签和所有这些版本保持一致。现有的 ci 检查要求所有 macOS/Linux 验证任务通过后，才能运行独立的发布任务。CI 只解析一次指定的检出版本，然后验证并发布该确切提交。发布使用 Node.js 24 和 GitHub OIDC：先发布到 npm，等待确切的程序包版本可用，然后将其注册到 MCP Registry。 如果 npm 发布成功后注册表注册失败，只使用现有的不可变标签重试注册：

gh workflow run publish-mcp.yml --ref main -f registry_tag=vX.Y.Z

将 vX.Y.Z 替换为已发布的标签。恢复流程会解析 refs/tags/vX.Y.Z、验证该标签对应的检出版本、跳过 npm 发布，并仅重试 MCP Registry 注册。

许可证

MIT

链接

• MinerU — 文档解析服务
• MinerU GitHub — 开源版本
• MCP 规范 — Model Context Protocol