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 — 模型上下文協議