Mineru MCP

🚀 mineru-mcp

Mineru-mcp 是为 MinerU 文档解析 API 提供支持的 MCP 服务器，可从 PDF、DOC 文档和图像中提取文本、表格和公式。

🚀 快速开始

使用 mineru-mcp 前，你需要安装 Node.js 18 及以上版本，并获取 MinerU API 密钥。

✨ 主要特性

• VLM 模型：针对复杂文档，准确率超 90%。
• Pipeline 模型：针对简单文档，处理速度快。
• 本地文件上传：支持从磁盘上传文件进行批量解析。
• 批量处理：一次最多可解析 200 个文档。
• 下载与重命名：可按原文件名提取 Markdown 文件。
• 页面范围选择：仅提取指定页面内容。
• 支持 109 种语言的 OCR。
• 针对 Claude Code 优化：与其他方案相比，可减少 73% 的令牌使用量。

📦 安装指南

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 文件中：

{
  "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 服务器图标 > 配置 > 高级 MCP 设置，然后添加：

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

Cherry Studio

在设置 > MCP 服务器 > 添加服务器中，将类型设置为 STDIO，命令设置为 npx，参数设置为 -y mineru-mcp，并添加环境变量 MINERU_API_KEY。或者在 JSON/代码模式下粘贴：

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

Witsy

在设置 > MCP 服务器中，添加一个新服务器，类型设置为 stdio，命令设置为 npx，参数设置为 -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 服务器。你需要将其部署在具有 HTTP 传输的公共 URL 之后。

📚 详细文档

工具列表

配置参数

你可以在 mineru.net 获取 API 密钥。

💻 使用示例

基础用法

解析单个 URL

mineru_parse({
  url: "https://example.com/document.pdf",
  model: "vlm",        // 可选: "pipeline" (默认) 或 "vlm" (90% 准确率)
  pages: "1-10,15",    // 可选: 页面范围
  ocr: true,           // 可选: 启用 OCR (仅适用于 pipeline 模型)
  formula: true,       // 可选: 公式识别
  table: true,         // 可选: 表格识别
  language: "en",      // 可选: 语言代码
  formats: ["html"]    // 可选: 额外的导出格式
})

检查任务进度

mineru_status({
  task_id: "abc-123",
  format: "concise"    // 可选: "concise" (默认) 或 "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,           // 可选: 最大结果数 (默认: 10)
  offset: 0,           // 可选: 跳过前 N 个结果
  format: "concise"    // 可选: "concise" 或 "detailed"
})

上传本地文件

mineru_upload_batch({
  directory: "/path/to/pdfs",  // 扫描指定目录中的支持文件
  // 或者
  files: ["/path/to/doc1.pdf", "/path/to/doc2.pdf"],  // 明确指定文件列表
  model: "vlm",        // 可选
  formula: true,       // 可选
  table: true,         // 可选
  language: "en",      // 可选
  formats: ["html"]    // 可选
})

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

以 Markdown 格式下载结果

mineru_download_results({
  batch_id: "batch-123",       // 来自 mineru_upload_batch 或 mineru_batch
  output_dir: "/path/to/output",
  overwrite: false             // 可选: 是否覆盖现有文件
})

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

典型的本地文件处理流程

mineru_upload_batch → mineru_batch_status (轮询) → mineru_download_results

📚 支持的文件格式

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

📚 使用限制

• 单个文件：最大 200MB，最多 600 页。
• 每日配额：高优先级 2000 页。
• 批量处理：每次请求最多 200 个文件。

📄 许可证

本项目采用 MIT 许可证。

📚 相关链接

• MinerU — 文档解析服务
• MinerU GitHub — 开源版本
• MCP Specification — 模型上下文协议