Paper Reader MCP

English | 简体中文

Paper Reader MCP is a local, read-only Model Context Protocol server for evidence-first analysis of research papers and slide decks. It supports PDF, DOCX, PPT, and PPTX files while minimizing tool round trips, repeated context, and unnecessary visual tokens.

The server converts a document once, stores a content-addressed local cache, and retrieves compact evidence for an entire question batch in one call. Original PDF regions are rendered only when textual evidence is insufficient for a visual claim.

Highlights

• Token-efficient retrieval: one paper_batch_search call handles up to 32 questions and returns a deduplicated evidence bank.

• Long-document support: adaptive context budgets, ranked chunks, exact numbered-reference routing, and compact wide-table serialization.

• Selective visual evidence: exact figure, table, or formula crops are limited to 500,000 pixels each and 1.3 million pixels per batch.

• Evidence traceability: results retain source page or slide references and stable evidence identifiers.

• Local and read-only: source documents are never modified or uploaded by the server.

• Persistent cache: unchanged files reuse Markdown, document structure, evidence indexes, and extracted assets.

• Weak-model oriented: the retrieval contract is designed to reduce planning and tool-loop errors in smaller models.

Supported formats

MCP tools

local document
    -> content hash and cache lookup
    -> Docling conversion
    -> Markdown + structured evidence index + assets
    -> one batched retrieval call
    -> optional single batched visual call
    -> page/slide-grounded answer

Installation

Python 3.10–3.12 is required. Python 3.10 is the tested version.

git clone https://github.com/oylx666/paper-reader-mcp.git
cd paper-reader-mcp
py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

Download the local PDF models once:

.\.venv\Scripts\docling-tools.exe models download layout tableformer rapidocr `
  --output-dir "$env:USERPROFILE\.cache\paper-reader-models"

The server deliberately fails instead of silently downloading missing models during a paper-reading request. This keeps first-call latency and network behavior predictable.

MCP configuration

Add a STDIO server entry to your MCP client, using absolute paths:

{
  "mcpServers": {
    "paper-reader": {
      "command": "C:\\path\\to\\paper-reader-mcp\\.venv\\Scripts\\paper-reader-mcp.exe",
      "env": {
        "PAPER_READER_MODELS": "C:\\Users\\YOUR_NAME\\.cache\\paper-reader-models"
      }
    }
  }
}

Ask questions naturally and include the local document path. Compatible clients are instructed to batch questions, avoid redundant follow-ups, and request visual evidence only when needed.

Configuration

Evaluation results

Tests used gpt-5.6-luna with low reasoning effort so retrieval and tool-use weaknesses could not be hidden by a stronger model.

Fifteen-question paper stress test

The original implementation used 13 retrieval calls. The current batch-first interface reduces the intended path to one retrieval call plus, only when required, one visual call. Gross token counts above therefore describe the conservative pre-batching stress run and are not the optimized lower bound.

TableFormer A/B on 16 manually reviewed paper tables

The reviewed reference was initially produced by the fast model and then manually checked, so this comparison may still favor that model. A fully independent cell-level HTML corpus and TEDS evaluation would be required for an unbiased model benchmark.

Visual input tokens are not reported because the platform did not expose modality-level token usage. Pixel counts were measured instead; missing visual-token telemetry must not be interpreted as zero usage.

Accuracy limits

• Reading order on complex multi-column pages is inferred and can be wrong.

• OCR output is unsuitable as sole evidence for exact quotations, formulas, subscripts, or very small table cells.

• Merged cells, dense tables, and chart markers should be verified against rendered source regions.

• Formula decoding is not proof of mathematical correctness; formula evidence remains visually verifiable.

• Office slide/page numbers are parser-derived and may differ from application UI numbering.

• The native PDF pipeline sacrifices layout, table, and OCR quality and is intended only as an emergency fallback.

Development

.\.venv\Scripts\python.exe -m pip install -e . pytest
.\.venv\Scripts\pytest.exe -q

The current suite contains 36 tests covering validation, caching, retrieval, evidence deduplication, long-context limits, table compaction, visual pixel budgets, and supported Office formats.

Status

This is an experimental research tool. Treat its output as retrieval evidence, not as an authoritative interpretation of a paper.