MinerU Document Explorer gives an agent three ways into your documents

Retrieve, Deep Read and Ingest as three separate suites

MinerU Document Explorer is described as an agent-native knowledge engine, and its organising idea is that an agent needs three different things from a document collection, so it ships three tool suites.

Retrieve is cross-collection search: BM25, vector, and hybrid with LLM reranking and query expansion. Query expansion is the part that decides whether the search is useful, since a bare keyword match over a folder of PDFs is where most retrieval attempts give up, and reranking is the part that fixes the ordering.

Deep Read is about navigating inside one document without loading the whole file: a table of contents, section reading, inline search and element extraction. That distinction is the whole point of the project, and the use cases follow from it. A research assistant can survey a folder of papers, a project knowledge base can answer architecture questions from indexed code and docs, a study companion can navigate textbooks with the toc and read tools, and an enterprise search can query contracts, reports and manuals in natural language.

Ingest is the third suite: building and maintaining an LLM wiki from raw documents, following the Karpathy LLM Wiki pattern. The project states that it was developed by the MinerU team and builds on QMD and on Karpathy's LLM Wiki, which is worth knowing because the lineage explains the design: this is the QMD search tool, wrapped in MCP and taught to an agent.

Deep reading without reading the file

The deep read tools are a small CLI with three verbs, and the examples use a real paper:

# View document structure
qmd doc-toc papers/attention-is-all-you-need.pdf

# Read specific sections by address
qmd doc-read papers/attention-is-all-you-need.pdf "line:45-120"

# Search within one document
qmd doc-grep papers/attention-is-all-you-need.pdf "self-attention"

doc-toc shows the structure of the document, doc-read takes an address, and the example address is a line range, line:45-120, which means the addressing is positional rather than section-name based. doc-grep searches inside the one document for a term such as self-attention.

For an agent, this changes the shape of a question. Instead of reading a forty page paper and spending the context window on it, the agent asks for the outline, then pulls the lines that matter, then greps for a term when it does not know where to look. The README makes the same point in the skill description, where the study companion use case is described as using doc_toc plus doc_read to navigate, doc_grep to search, and a wiki of key concepts on top.

The same three verbs are exposed as MCP tools with underscores instead of hyphens, and the CLI is the direct way to try them before wiring an agent up.

Why the MCP server exists instead of only a CLI

The README draws the distinction between the MCP server and the CLI in one paragraph, and it is the strongest argument in the document for the whole design.

The MCP server runs as a persistent process, so the LLM models used for embeddings, the reranker and query expansion are loaded once and stay in memory across requests. CLI commands like qmd query must reload all models on every invocation, which the README puts at roughly five to fifteen seconds of startup overhead each time. The advice is explicit: for agent workflows, always prefer the MCP server.

That is a concrete engineering reason, not a preference. A search that takes ten seconds to start is unusable inside a chat turn, and an agent that has to wait for it will stop making calls.

There are two transport modes, and the table pairs each with the clients it suits. The stdio mode, qmd mcp, is for Claude Desktop and Claude Code, where the client spawns and manages the process. The HTTP daemon mode, qmd mcp --http --daemon, is for Cursor, Windsurf, VS Code and multi-client setups, where one shared persistent server serves everyone.

qmd mcp --http --daemon             # default port 8181
qmd mcp --http --daemon --port 8080 # custom port

# Verify server is running
curl http://localhost:8181/health

# Stop the daemon
qmd mcp stop

The health endpoint and a stop command are small things that matter in practice, since a daemon on port 8181 is something you will want to check and something you will want to shut down cleanly.

Fifteen tools, and the configuration for each client

The MCP server exposes fifteen tools, and the client configuration is the same shape everywhere, which is the usual pattern for MCP.

For a client that spawns the process, the entry is a command and its arguments:

{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

That block is what the documentation asks you to add to .cursor/mcp.json or the global variant, to the Claude Desktop configuration at ~/Library/Application Support/Claude/claude_desktop_config.json, and to the Claude Code settings at ~/.claude/settings.json, where the alternative is the claude mcp add qmd -- qmd mcp command.

For a client that connects to a running server, the entry is a URL instead:

{
  "mcpServers": {
    "qmd": {
      "url": "http://localhost:8181/mcp"
    }
  }
}

For Windsurf, VS Code and other MCP clients the documentation gives the same two rules in prose: use the command and args for stdio, or start the HTTP daemon and point the client at the local address.

The naming is worth noticing. The server is called qmd everywhere, even though the package is mineru-document-explorer, which keeps the configuration short and consistent with the QMD tool it descends from.

A skill that teaches the agent how to use the tools

Fifteen tools is a lot of surface for an agent to guess at, and the project ships an answer to that problem: a built-in Agent Skill at skills/mineru-document-explorer/SKILL.md that teaches AI agents how to use the full tool suite effectively, with decision trees, usage patterns and best practices for all fifteen MCP tools.

The installation is three commands, and it works for both npm and source installs:

# Install the skill (works with both npm and source installs)
qmd skill install              # local project (.agents/skills/)
qmd skill install --global     # global (~/.agents/skills/)

# Or from source repo
claude skill add ./skills/mineru-document-explorer/SKILL.md

The distinction between local and global is a scope decision: a project skill is committed with the repository and shared with the team through version control, while a global one follows the user across projects.

The same agent-first attitude appears in the quick start, which tells an agent to follow a quickstart document and walk the user through configuration. There is even a line in the package scripts for the inspector, npx @modelcontextprotocol/inspector pointed at the MCP entry point, which is the standard way to look at an MCP server's tools by hand. For a project whose audience is an agent rather than a person, building the onboarding path for the agent is a first-class feature.

The demo is a workshop, not a screenshot

The demo folder is unusual for a project of this kind, and the file list explains why. Alongside demo/README.md and demo/setup.sh there are AGENT-PROMPT.md, EXERCISES.md, INSTRUCTOR.md and WORKSHOP.md, along with a fetch_arxiv.py script, and each of the teaching files has a Chinese counterpart.

That is a workshop kit. The README describes what the demo contains: a complete end-to-end example in which an AI agent automatically reads about ten arXiv papers on retrieval augmented generation, builds an interlinked wiki knowledge base, and writes a research survey, with a Demo Guide for step-by-step instructions.

So the demo is not a screenshot of a search box. It is the whole loop, retrieval, ingest and synthesis, run against real papers fetched from arXiv, with exercises and an instructor guide around it. The wiki is the output of the Ingest suite, and the survey is what the agent writes once the wiki exists.

The presence of a Chinese documentation set, a README-zh.md at the root and parallel Chinese versions of the demo files, points at a project maintained with a Chinese-speaking audience in mind, and the repository also carries a CLAUDE.md, a .claude-plugin/ directory and a .pi/ directory, which are the conventions for making a repository usable by coding agents.

MIT terms, a 1.0.9 package, and a quiet repository

The licence is MIT, with the LICENSE file at the repository root, and the package is published to npm as mineru-document-explorer at version 1.0.9, published rather than private.

The package layout is informative. The binary is qmd, mapped to bin/qmd, and the published files are dist/, bin/, skills/, references/, the README and the licence. Shipping skills and references in the package is what makes qmd skill install work for a user who installed from npm.

The runtime dependencies begin with the MCP SDK at ^1.25.1 and better-sqlite3 at ^12.4.5, so the index is a local SQLite database, which is the important architectural fact: the search runs against a local index rather than against a remote service. The scripts show the rest of the tool, with vitest for the tests, a build that compiles TypeScript and copies the Python backends into dist, and separate commands for update, embed, search, vsearch and rerank, so the embedding and reranking stages are first-class commands rather than hidden inside a search.

The repository is broader than a typical npm package: there is a flake.nix, a bun.lock, a migrate-schema.ts, a finetune/ directory, a WIKI-PROGRESS.md, a CHANGELOG.md and an example-index.yml, along with a demo/ and docs/ tree.

The maintenance picture is the weak point. There are no GitHub releases, and the last push was on 2026-04-26, more than six months before the present date. The version in the package metadata is 1.0.9 and the project is not archived, but a team depending on the index schema or the MCP tool set should verify the state of the branch before planning around it.

Editorial conclusion

mineru-document-explorer fits a team that wants an agent to answer questions across a document collection, and to navigate a single long paper by structure rather than by dumping it into a prompt, since the deep read tools and the persistent MCP server address exactly those two problems. It does not fit a project that needs answers in milliseconds, because the model loading cost is paid once per server rather than per question and the CLI pays it every time, and it does not fit a team unwilling to run a local index. Before adopting it, start the HTTP daemon rather than the stdio transport, keep the health check in your runbook, and check the last push date against your roadmap, since the repository was last pushed on 2026-04-26 and has no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. opendatalab/MinerU-Document-Explorer on GitHub
4. README