The pdf-search-mcp server provides full-text search and rendering for PDF collections via MCP tools — fully offline, with no API keys required.
Search PDFs (search): Instant, ranked full-text search across indexed PDFs using SQLite FTS5 syntax:
Phrases, AND/OR/NOT, prefix (term*), and proximity (NEAR) operators
Automatic German umlaut/eszett expansion (ß↔ss, ä↔ae, ö↔oe, ü↔ue)
Auto-relaxation when no results match (drops least-represented terms, then falls back to OR)
Ranked results (BM25 + match density) with file, page, and snippet
Read page text (read_page): Retrieve the full normalized text of any specific page from an indexed PDF.
Render page as image (read_page_image): Render a PDF page or cropped region as a PNG — useful for formulas, diagrams, and tables that text extraction misses. Cropped regions auto-scale DPI for maximum detail.
Index statistics (stats): View file count, page count, database size, and active PDF renderer (CoreGraphics on macOS, PyMuPDF on Linux/Windows).
Deployment: Runs over stdio (per-client subprocess) or HTTP (shared server), with Docker support. Uses SQLite FTS5 and local PDF files with incremental indexing.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pdf-search-mcp find pages mentioning 'garbage collection'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for full-text search across PDF document collections. Built for AI agents — index once, search instantly from any MCP client.
Search entire collections — pre-indexes all PDFs for instant ranked results with snippets, not one file at a time
Fully offline — no API keys, no cloud services, just SQLite FTS5 and PyMuPDF
Page rendering — render pages as PNG for formulas, diagrams, and tables; crop to a region with auto-DPI scaling for detail shots
Dual renderer — CoreGraphics on macOS (sharper math fonts), PyMuPDF on Linux/Windows
German-aware — automatic expansion of ß↔ss, ä↔ae, ö↔oe, ü↔ue so both spellings match
stdio or HTTP — per-client subprocess by default, or a standalone shared server for trusted networks (Dockerfile included)
pip install pdf-search-mcpgit clone https://github.com/renvk/pdf-search-mcp.git
cd pdf-search-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .Requires Python 3.10+. On macOS, pyobjc-framework-Quartz is installed automatically for native CoreGraphics PDF rendering (sharper formula and math font output). On Linux/Windows, PyMuPDF is used as the renderer.
Related MCP server: mcp-pdf-tools
PDF_SEARCH_DIR=/path/to/your/pdfs python -m pdf_search_mcp.pdf_search indexThe server runs over stdio. Example for Claude Code:
# project-scoped (only available in the current directory)
claude mcp add pdf-search -- pdf-search-mcp
# or global (available in all projects)
claude mcp add --scope global pdf-search -- pdf-search-mcpFor other MCP clients, add to your MCP config:
{
"mcpServers": {
"pdf-search": {
"command": "pdf-search-mcp"
}
}
}Ask your AI agent to search your PDFs — it will use the search, read_page, and read_page_image tools automatically.
Environment Variable | Default | Description |
| (none) | Path to your PDF directory (required for first index, remembered after) |
|
| Path to the SQLite database file |
The server has two transports:
stdio (default, no flags): each MCP client launches its own server subprocess on the same machine. Use this for single-machine setups.
http: one standalone server shares one indexed PDF collection with multiple clients over a trusted network:
pdf-search-mcp --transport http --host 0.0.0.0 --port 8000The MCP endpoint is http://<server>:8000/mcp. Connecting from Claude Code:
claude mcp add --transport http --scope user pdf-search http://<server>:8000/mcpSecurity: the HTTP transport has no authentication or TLS. Run it only on trusted networks (LAN, VPN) and never expose it to the internet. The default
--host 127.0.0.1keeps it local to the machine; binding0.0.0.0is an explicit opt-in.
Note: over HTTP,
read_page_imagereturns the rendered PNG as inline MCP image content, so page rendering works for clients on other machines (including clients without filesystem access, such as Claude Desktop). Over stdio it returns a file path for the client to open, as before.
The repository includes a Dockerfile for container hosts (home servers, NAS devices). On startup the container runs an incremental index sync against the mounted PDF directory (only new, changed, and deleted files are processed) and then serves on port 8000:
git clone https://github.com/renvk/pdf-search-mcp.git
cd pdf-search-mcp
docker build -t pdf-search-mcp .
docker run -d --name pdf-search \
-p 8000:8000 \
-v /path/to/pdfs:/pdfs:ro \
-v pdf-index:/data \
pdf-search-mcpOr with Docker Compose:
services:
pdf-search:
build: .
ports:
- "8000:8000"
volumes:
- /path/to/pdfs:/pdfs:ro
- pdf-index:/data
restart: unless-stopped
volumes:
pdf-index:New PDFs in the mounted directory are picked up on container restart, or immediately with:
docker exec pdf-search python -m pdf_search_mcp.pdf_search indexSet PDF_SEARCH_INDEX_ON_START=0 in the container environment to skip the index sync (e.g. when the index is maintained by an external job).
The pdf_search.py module doubles as a CLI for indexing and direct search:
# Build index (first time — PDF_SEARCH_DIR required)
PDF_SEARCH_DIR=/path/to/pdfs python -m pdf_search_mcp.pdf_search index
# Subsequent syncs (path remembered from first index)
python -m pdf_search_mcp.pdf_search index
# Search from command line
python -m pdf_search_mcp.pdf_search search "query terms"
# Read a specific page
python -m pdf_search_mcp.pdf_search read filename.pdf 5
# Show index statistics
python -m pdf_search_mcp.pdf_search stats
# Report extraction-quality problems (scanned files needing OCR,
# stale normalization, broken font mappings, near-empty pages)
python -m pdf_search_mcp.pdf_search quality
# Rebuild index from scratch (path remembered)
python -m pdf_search_mcp.pdf_search reindexUses SQLite FTS5 query syntax:
Syntax | Example | Description |
Terms |
| Both terms must appear (implicit AND) |
Phrase |
| Exact phrase match |
OR |
| Either term |
NOT |
| Exclude term |
Prefix |
| Prefix matching |
NEAR |
| Terms within 10 tokens of each other |
Auto-quoting: Terms containing any special character (dots, hyphens, commas, slashes, colons, ...) are automatically quoted (e.g., ISO-27001 becomes "ISO-27001", 1:100 becomes "1:100") because FTS5 treats these as token separators or operators. Query preparation guarantees valid FTS5 syntax — stray quotes are dropped, unbalanced parentheses are repaired, and dangling AND/OR operators are trimmed. The one exception is NOT without a left operand (FTS5's NOT is binary): it is passed through and returns a clear error, because silently searching the excluded term would invert the query's meaning.
German expansion: Umlauts and eszett are automatically expanded to their digraph equivalents and vice versa (ß↔ss, ä↔ae, ö↔oe, ü↔ue). Searching for Größe also finds Groesse, and Weißbuch also finds Weissbuch. Reverse expansion (ss→ß) replaces one position at a time. Expansion also applies inside NEAR() expressions.
Auto-relaxation: When a multi-term query returns no results (all terms must appear on the same page), the search automatically relaxes: first by dropping the term least represented in the corpus (chosen by uncapped match counts), then by OR-ing all terms. A note in the output explains what was actually searched. Structured queries (explicit AND, OR, NOT, NEAR, parentheses) are not relaxed.
Tool | Parameters | Description |
|
| Full-text search with ranked results and snippets (limit range 1-50) |
|
| Read the full text of a specific page |
|
| Render a page (or cropped region) as PNG. |
| (none) | Show index statistics (file count, pages, DB size, renderer) |
When the same filename exists in several subfolders, read_page and read_page_image require the subfolder parameter ("" selects the root folder); an unspecified subfolder returns an error listing the candidates instead of picking one arbitrarily.
from pdf_search_mcp import (
search_with_relaxation, search_pdfs, prepare_query,
read_pdf_page, render_pdf_page, index_pdfs,
)
# Index PDFs
index_pdfs("/path/to/pdfs")
# Search with the full pipeline (auto-quoting, German expansion,
# relaxation) — same behavior as the MCP search tool and the CLI
results, note = search_with_relaxation("ISO-27001 Anhang", limit=5)
for r in results:
print(f"{r['subfolder']}/{r['file']} p.{r['page']}: {r['snippet']}")
# Low-level: search_pdfs takes a RAW FTS5 MATCH string (no preparation).
# Run user input through prepare_query first.
results = search_pdfs(prepare_query("garbage collection"), limit=5)
# Read full page text
text = read_pdf_page("document.pdf", 42)
# Render full page as PNG
png_path = render_pdf_page("document.pdf", 42)
# Render cropped region (DPI auto-scales to maximize detail)
png_path = render_pdf_page("document.pdf", 42, region=[0.0, 0.5, 1.0, 0.8])Indexing incrementally syncs your PDF directory into a SQLite FTS5 virtual table — on first run all PDFs are indexed; afterwards only new, changed (by mtime/size), and deleted files are processed, each committed individually so an interrupted run resumes where it stopped. Only page content is searchable; filenames, subfolders, and page numbers are stored as unindexed metadata so query terms cannot match them. Directories starting with _ are skipped. Extracted text is normalized before indexing — typographic ligatures are decomposed (efficiency → efficiency), words split by line-break hyphenation are rejoined, and invisible soft hyphens are removed — so words that would otherwise never match a query do. read_page applies the same normalization, so the text you read is exactly the text that was searched.
Upgrading: a pre-0.3 index (searchable metadata columns) is refused with a clear error; an index built before text normalization keeps working but stores unnormalized text. In either case, run
python -m pdf_search_mcp.pdf_search reindexonce to rebuild.
Searching runs FTS5 MATCH queries and re-ranks results by combining BM25 relevance with match density — pages where search terms cluster together score higher than pages with the same terms scattered throughout. The density signal blends term concentration (matches per character) and spatial clustering (how tightly grouped the matches are).
Reading re-opens the original PDF file on disk (path resolved via the stored pdf_dir metadata) for full page text or image rendering. Region crops auto-scale DPI to fill a 1568 px long-edge budget, maximizing detail without producing oversized images.
The database stores the text content only — original PDFs are accessed on disk for read_page and read_page_image. Rendering uses CoreGraphics on macOS and PyMuPDF elsewhere.
MIT
Read the full text of a specific page from an indexed PDF.
Use after search() to read the complete page content around a match. If the result contains garbled text, broken symbols, or unreadable formulas, use read_page_image() instead — it renders the page as a PNG that preserves formulas, diagrams, and tables exactly. For tables and dense data, crop to the relevant region to read values reliably.
Args: filename: PDF filename exactly as shown in search results. page: 1-based page number. subfolder: Subfolder as shown in search results. Required when duplicate filenames exist; pass "" for the root folder.
Returns: Full extracted text of the page.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | ||
| page | Yes | ||
| subfolder | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the tool returns full extracted text and notes when output may be garbled, advising an alternative. Does not mention error cases or side effects, but for a simple read tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence summary, usage guidelines, parameter details, and return value. Each sentence is informative and concise, with no redundant or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (not shown), the description states 'Returns: Full extracted text of the page,' which is sufficient. It also covers practical context (when to use image version, subfolder handling). The tool is simple, and the description covers all necessary aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds detailed meaning: filename must be exact from search results, page is 1-based, subfolder is required when duplicates exist and empty string means root. This fully clarifies parameter usage beyond the schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Read the full text of a specific page from an indexed PDF,' which is a specific verb+resource pair. It distinguishes itself from sibling tools like read_page_image (renders as PNG) and search (used before reading).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use after search() to read the complete page content around a match' and 'If the result contains garbled text... use read_page_image() instead — it renders the page as a PNG.' Also explains when subfolder parameter is required, providing clear use vs. non-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a PDF page (or cropped region) as a PNG for visual inspection.
Use instead of read_page() when text extraction misses formulas, diagrams, or tables.
Workflow:
First call: render the full page (no region, default dpi) to orient yourself. Do NOT raise dpi — default 140 already fills the vision model's 1568 px input limit. Higher DPI just gets downscaled.
ALWAYS crop before reading values. Tables, formulas, and dense data are NOT reliably readable at full-page scale. Call again with region to crop the area of interest. DPI auto-scales to fill 1568 px for the crop — do NOT set dpi manually, it is computed automatically.
Args: filename: PDF filename exactly as shown in search results. page: 1-based page number. dpi: Render resolution (default 140, range 1-600). Leave at default for full-page renders. Ignored when region is set (auto-scaled to fill 1568 px). region: Crop box [x1, y1, x2, y2], each value 0.0–1.0, top-left origin. Required for reading values from tables, formulas, or figures — full-page scale is not reliable for these. Example: [0.0, 0.5, 1.0, 0.8] = band from 50–80% down the page. subfolder: Subfolder as shown in search results. Required when duplicate filenames exist; pass "" for the root folder.
Returns: stdio transport: the PNG file path on the first line — open it with your file-reading tool to view. Full-page renders append a crop-advisory line after the path; when passing the result to a file reader, use only the first line. http transport: the rendered PNG as inline image content (no file access needed). Full-page renders include the crop advisory as an additional text item. On error: a plain-text message describing the problem.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | ||
| page | Yes | ||
| dpi | No | ||
| region | No | ||
| subfolder | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully carries transparency. It discloses return behavior for both stdio and HTTP transports, error handling, DPI auto-scaling when region is set, and the crop advisory line appended to full-page renders.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (purpose, workflow, args, returns) and front-loaded with key info. Though lengthy, every sentence adds value; minor redundancy could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description fully covers return types for both transports, error messages, and the crop advisory. It addresses all edge cases: DPI auto-scaling, region usage, subfolder handling, and duplicate filenames.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description explains each parameter in detail: filename source, 1-based page, DPI range and default with behavior when region is set, region format and example, subfolder usage. Adds constraints and usage tips beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool renders a PDF page or cropped region as PNG for visual inspection, and explicitly distinguishes it from read_page() for cases where text extraction misses formulas, diagrams, or tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a detailed workflow: first render full page to orient, then crop for reading values. It warns against raising DPI, explains when cropping is mandatory, and addresses duplicate filenames with subfolder. It directly recommends using this tool instead of read_page() for specific contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search indexed PDFs using FTS5 full-text search.
Supports FTS5 syntax: phrases ("exact phrase"), AND (implicit), OR, NOT, prefix (term*), NEAR(term1 term2, 10), parentheses.
Terms with special characters (dots, hyphens, colons, slashes, ...) are auto-quoted — FTS5 treats them as token separators. You can also quote them yourself: "13445-3", "v2.1".
German ß↔ss / ä↔ae / ö↔oe / ü↔ue variants are expanded automatically.
When no results match all terms (implicit AND), the query is automatically relaxed: first by dropping the term least represented in the corpus, then by OR-ing all terms. A note at the top explains what was searched. Structured queries (explicit operators, NEAR, parentheses) are never relaxed.
Args: query: Search query string. limit: Maximum number of results (default 10, range 1-50).
Returns: Formatted search results with file, subfolder, page, and snippet.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses behavioral traits: auto-quoting special characters, German character expansion, automatic query relaxation, and structured queries not being relaxed. It also mentions a note explaining relaxed searches.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with front-loaded purpose and detailed syntax info. It is reasonably concise, though some sections (like auto-relaxation) could be slightly more condensed without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of FTS5 search with special syntax and auto-relaxation, the description covers all necessary aspects. Output schema exists (described in return format), and no additional info is needed for the tool's usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description adds meaning for both parameters: 'query' is the search string, 'limit' is max results with default 10 and range 1-50. However, it does not elaborate on edge cases or behavior beyond basic details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search indexed PDFs using FTS5 full-text search.' It uses a specific verb (search) and resource (indexed PDFs), and is distinct from sibling tools like read_page, read_page_image, and stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (to search text in PDFs) but does not explicitly state when to use this tool versus alternatives or provide exclusions. Sibling differentiation is implicit but no direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show PDF search index statistics (file count, page count, DB size, renderer).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read-only operation with no side effects, aligning with the lack of annotations. While no additional behavioral traits are disclosed, nothing is hidden; the tool is straightforward.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that includes all necessary information without extraneous words. It is front-loaded with the verb 'Show' and key object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no annotations, and an existing output schema, the description is sufficiently complete. It explains what the tool returns without needing to document return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description correctly avoids parameter details. The baseline for zero parameters is 4, and the description adds no confusion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: showing PDF search index statistics with specific metrics (file count, page count, DB size, renderer). It effectively distinguishes from sibling tools like read_page and search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is clear and the sibling context implies when to use (for aggregate stats vs. individual pages). However, no explicit guidance on when not to use or alternatives is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.0read_pageread_page_imagesearchstatsScored across 4 tools
Each tool has a distinct purpose: search for discovering matches, read_page for text extraction, read_page_image for visual rendering of problematic content, and stats for index overview. No functional overlap.
All tool names follow a consistent verb_noun pattern in snake_case: read_page, read_page_image, search, stats. The two 'read' tools are clearly differentiated by their object (page vs page_image).
Four tools is well-scoped for a PDF search MCP: search, two complementary view methods (text and image), and index statistics. No tool is superfluous, and the count aligns with typical server sizes.
Covers the core workflow of searching and viewing PDFs with both text and image fallbacks. A minor gap is the lack of a tool to list all indexed files or manage the index, but for search-oriented usage it is sufficient.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for detecting and redacting PII (Personally Identifiable Information) in PDF documents.
MCP server for searching Airweave collections with natural language queries.
Query your own PDFs and documents from any MCP client. Every answer cites the page it came from.
