pdfsearch-mcp

Minimal MCP server that indexes and searches PDFs (AGLC4 by default) for use by LLM tools (Claude Desktop, Claude Code, Codex, etc.). Search runs locally with no external APIs.

Quickstart (Node)

• Place the PDF at data/AGLC4.pdf.
• Install: npm install
• Build index: npm run index
• Run server (stdio): npm run dev (TS) or npm start (compiled)

Quickstart (Docker)

• Build: docker build -t pdfsearch-mcp .
• Run (mount data):
  • mkdir -p data && cp path/to/AGLC4.pdf data/AGLC4.pdf
  • docker run -i --rm -v "$PWD/data:/app/data" pdfsearch-mcp

The server communicates over stdio per MCP; configure your client/tool to launch the command and speak MCP.

Making the PDF Machine-Readable (OCR)

• The indexer auto-detects image-only PDFs. If minimal text is found, it runs OCR via ocrmypdf and writes data/AGLC4.ocr.pdf, then indexes that.
• Local install:
  • macOS: brew install ocrmypdf tesseract
  • Debian/Ubuntu: sudo apt-get install -y ocrmypdf tesseract-ocr
• Environment:
  • OCR_LANG (default eng) — tesseract language(s), e.g. eng+fra.
  • OCR_FORCE=1 — force OCR even if a text layer exists.
• Docker image already includes OCR tools.

Commands

• npm run index — Extracts text from the PDF and creates a local search index under data/index/.
• npm run dev — Runs the MCP server in TypeScript via tsx.
• npm run build — Compiles TypeScript to dist/.
• npm start — Runs the compiled server.
• npm run search -- "query" — Quick local search without MCP.
• npm run health — Prints whether the PDF and index are present.
• npm run setup — Install deps, index the default PDF, and start the server.
• npm run list-tools — Minimal MCP client printing the server tool list.
• npm run call-tool -- '{"name":"searchpdf-mcp","arguments":{"query":"..."}}' — Call a tool via MCP stdio and print JSON.

MCP Integration

• Transport: stdio
• Command (compiled): node dist/src/server.js
• Command (dev): npm run dev
• Tools:
  • searchpdf-mcp — input { query: string, limit?: number, source?: string, before?: number, after?: number, budget?: number, phraseBoost?: number, phraseOnly?: boolean }; returns text snippets with scores and added context from neighboring sections.

Config

• PDF_PATH — Path to the PDF to index; defaults to data/AGLC4.pdf.
• OCR_LANG — OCR language(s) for ocrmypdf (default eng), e.g. eng+fra.
• OCR_FORCE=1 — Force OCR even if a text layer exists.
• MCP_CMD — Override the server command used by list-tools/call-tool (e.g. "node dist/src/server.js").
• before/after/budget — Optional context tuning parameters for previews.

config.json

You can configure source and index directories and auto-index behavior via a config.json at the repo root:

{
  "pdfDir": "data",          // directory containing source PDFs
  "indexDir": "data/index",  // directory to store built indexes
  "autoIndex": true,          // scan + build missing/stale indexes on startup
  "watch": true               // watch pdfDir for changes and auto-index
}

Environment variables override these values: PDF_DIR, INDEX_DIR, AUTO_INDEX, WATCH_INDEX.

Multiple PDFs

• Index per PDF: npm run index -- --pdf path/to/SomeDoc.pdf writes to <indexDir>/SomeDoc/index.json (and updates the legacy <indexDir>/index.json).
• Tool selection: pass source in searchpdf-mcp args (name, basename, or path). Examples:
  • { "source": "data/AGLC4.pdf", "query": "neutral citation" }
  • { "source": "AGLC4", "query": "ibid" }

Auto-indexing

• On startup, the server scans pdfDir for *.pdf and builds indexes for any new or changed files (via content hash).
• If watch is true, the server watches pdfDir and automatically reindexes PDFs when they are added or updated.

Claude Desktop Example

Add to your Claude Desktop config (merge keys accordingly):

{
  "mcpServers": {
    "aglc4": {
      "command": "node",
  "args": ["dist/src/server.js"],
      "env": {}
    }
  }
}

For Docker:

{
  "mcpServers": {
    "aglc4": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "${HOME}/aglc4-data:/app/data",
        "pdfsearch-mcp"
      ]
    }
  }
}

Ensure ${HOME}/aglc4-data/AGLC4.pdf exists and that you’ve run indexing (or let the server/client invoke indexing step before use).

Notes

• Indexing happens locally; only the canonical PDF is stored in data/.
• If you update the PDF, re-run npm run index.
• For client configuration, point tools to execute npm start (or the Docker image) as an MCP server.
• On startup, the server logs an index summary and warns if the index appears stale (PDF changed). Re-run indexing if prompted.

Agent Usage

• See docs/agent-usage.md for comprehensive MCP integration details, example requests, and tuning options.

Changelog

• 0.2.0
  • Rename project to pdfsearch-mcp and tool to searchpdf-mcp.
  • Richer search previews with surrounding context and page numbers.
  • Extract shared logic to src/lib/pdf.ts; add Vitest tests.
  • Reindexing flow now tags pages using pdf-parse pagerender.
• 0.1.0
  • Initial release.