MinerU document parsing API — PDFs, images, DOCX, PPTX with OCR and batch processing.
MCP server for MinerU document parsing API — extract text, tables, and formulas from PDFs, DOCs, and images.
| Tool | Description |
|---|---|
mineru_parse | Parse a document URL |
mineru_status | Check task progress, get download URL |
mineru_batch | Parse multiple URLs (max 200) |
mineru_batch_status | Get batch results with pagination |
mineru_upload_batch | Upload local files for batch parsing |
mineru_download_results | Download results as named markdown files |
Requires Node.js 18+ and a MinerU API key.
# 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
Add to your claude_desktop_config.json:
| OS | Config path |
|---|---|
| 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"
}
}
}
}
Add to .vscode/mcp.json (workspace) or open Command Palette > MCP: Open User Configuration (global):
{
"servers": {
"mineru": {
"command": "npx",
"args": ["-y", "mineru-mcp"],
"env": {
"MINERU_API_KEY": "your-api-key"
}
}
}
}
Note: VS Code uses
"servers"as the top-level key, not"mcpServers". Other VS Code forks (Trae, Void, PearAI, etc.) typically use this same format.
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):
{
"mcpServers": {
"mineru": {
"command": "npx",
"args": ["-y", "mineru-mcp"],
"env": {
"MINERU_API_KEY": "your-api-key"
}
}
}
}
Add to ~/.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"
}
}
}
}
Open MCP Servers icon in Cline panel > Configure > Advanced MCP Settings, then add:
{
"mcpServers": {
"mineru": {
"command": "npx",
"args": ["-y", "mineru-mcp"],
"env": {
"MINERU_API_KEY": "your-api-key"
}
}
}
}
In Settings > MCP Servers > Add Server, set Type to STDIO, Command to npx, Args to -y mineru-mcp, and add environment variable MINERU_API_KEY. Or paste in JSON/Code mode:
{
"mineru": {
"name": "MinerU",
"command": "npx",
"args": ["-y", "mineru-mcp"],
"env": {
"MINERU_API_KEY": "your-api-key"
},
"isActive": true
}
}
In Settings > MCP Servers, add a new server with Type: stdio, Command: npx, Args: -y mineru-mcp, and set environment variable MINERU_API_KEY to your API key.
Alternatively, edit ~/.codex/config.toml directly:
[mcp_servers.mineru]
command = "npx"
args = ["-y", "mineru-mcp"]
[mcp_servers.mineru.env]
MINERU_API_KEY = "your-api-key"
Alternatively, edit ~/.gemini/settings.json directly:
{
"mcpServers": {
"mineru": {
"command": "npx",
"args": ["-y", "mineru-mcp"],
"env": {
"MINERU_API_KEY": "your-api-key"
}
}
}
}
On Windows, npx requires a shell wrapper. Replace "command": "npx" with:
{
"command": "cmd",
"args": ["/c", "npx", "-y", "mineru-mcp"],
"env": {
"MINERU_API_KEY": "your-api-key"
}
}
For CLI tools on Windows:
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 only supports remote MCP servers over HTTPS — local stdio servers like this one are not directly supported. You would need to deploy behind a public URL with HTTP transport.
| Environment Variable | Default | Description |
|---|---|---|
MINERU_API_KEY | (required) | Your MinerU API Bearer token |
MINERU_BASE_URL | https://mineru.net/api/v4 | API base URL |
MINERU_DEFAULT_MODEL | pipeline | Default model: pipeline or vlm |
Get your API key at mineru.net
mineru_parse({
url: "https://example.com/document.pdf",
model: "vlm", // optional: "pipeline" (default) or "vlm" (90% accuracy)
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"
})
Concise output: done | abc-123 | https://cdn-mineru.../result.zip
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
})
Returns batch_id for tracking. Each file's original name is preserved via data_id (spaces become underscores).
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
})
Output filenames are derived from data_id (e.g., my_paper_title.md). Spaces in original filenames become underscores.
mineru_upload_batch → mineru_batch_status (poll) → mineru_download_results
MIT
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y mineru-mcpMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-linxule-mineru": {
"command": "npx",
"args": [
"-y",
"mineru-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencemineru-mcpnpmMinerU works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.