How do I use io.github.Xvvln/pdf-reader-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@io.github.Xvvln/pdf-reader-mcp Read /Users/me/Documents/report.pdf as text." 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.

io.github.Xvvln/pdf-reader-mcp

by Xvvln

Overview Schema Source Related Servers Discussions Admin

Python

Local

pdf-reader-mcp

一个用于读取和分析 PDF 文件的 MCP 服务器。它可以为支持 MCP（Model Context Protocol）的客户端提供 PDF 文本、页面图片、表格、链接、批注、目录、元数据和基础文本统计。

A PDF-focused MCP server for extracting text, rendered pages, tables, links, annotations, outlines, metadata, and text statistics from PDF files.

Package name

GitHub repository: pdf-reader-mcp
MCP Registry name: io.github.Xvvln/pdf-reader-mcp
PyPI package: pdf-insight-mcp
CLI commands: pdf-reader-mcp and pdf-insight-mcp

pdf-reader-mcp is the project name. The PyPI package is published as pdf-insight-mcp because the pdf-reader-mcp package name is not available on PyPI.

Related MCP server: MCP PDF Server

Features

Tool	What it does
`get_pdf_info`	Read document metadata, page count, file size, and encryption status.
`read_pdf_as_text`	Extract text from selected pages with page and character limits.
`read_pdf_as_images`	Render selected pages as base64-encoded images.
`get_pdf_outline`	Read bookmarks and outline entries.
`search_pdf_text`	Search text and return per-match page context.
`extract_pdf_tables`	Extract structured tables when PyMuPDF can detect them.
`extract_pdf_images`	Extract embedded PDF images.
`get_pdf_page_info`	Inspect one page's size, text, images, links, and rotation.
`extract_pdf_links`	Extract external URLs and internal page jumps.
`get_pdf_annotations`	Read comments, highlights, and annotation metadata.
`get_pdf_text_stats`	Compute text, line, paragraph, and scan-likelihood stats.
`compare_pdf_pages`	Compare text similarity between two pages.

Quick start

Install uv if you do not already have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Run the server directly from PyPI:

uvx pdf-insight-mcp

Or install it first:

python -m pip install pdf-insight-mcp
pdf-reader-mcp

MCP client configuration

Use the published PyPI package:

{
  "mcpServers": {
    "pdf-reader": {
      "command": "uvx",
      "args": ["pdf-insight-mcp"]
    }
  }
}

Use a local checkout for development:

{
  "mcpServers": {
    "pdf-reader": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/pdf-reader-mcp",
        "run",
        "pdf-reader-mcp"
      ]
    }
  }
}

Replace /absolute/path/to/pdf-reader-mcp with the absolute path to this repository on your machine.

Common usage

Ask your MCP client to call tools with an absolute PDF path. Example requests:

Read /Users/me/Documents/report.pdf as text.
Search /Users/me/Documents/report.pdf for "baseline characteristics".
Render pages 1-3 of /Users/me/Documents/report.pdf as images.
Extract links and annotations from /Users/me/Documents/review.pdf.

For large PDFs, prefer small page ranges first. For scanned or layout-sensitive PDFs, use read_pdf_as_images with a small pages range and moderate dpi.

Limits and behavior

read_pdf_as_text defaults to at most 50 pages and 200000 returned characters.
read_pdf_as_images rejects requests above 20 pages.
read_pdf_as_images defaults to an overall image payload cap of about 20 MB.
extract_pdf_images returns at most 20 embedded images but reports the actual detected total.
Encrypted PDFs are rejected unless they are already accessible without a password.
Scanned PDFs may have little or no extractable text. Use image rendering or OCR outside this server when needed.

Development

Install dependencies:

uv sync --extra dev

Run tests:

uv run pytest -q

Build the package:

uv build
uvx twine check dist/*

Run the local server:

uv run pdf-reader-mcp

Release

Releases are published through GitHub Actions.

Before the first release, configure PyPI Trusted Publishing with:

PyPI project name: pdf-insight-mcp
Owner: Xvvln
Repository name: pdf-reader-mcp
Workflow filename: publish.yml
Environment name: leave empty

Then release by bumping versions in pyproject.toml and server.json, committing the change, and pushing a version tag:

git tag vX.Y.Z
git push origin main --tags

The Publish workflow runs tests, builds the Python package, publishes to PyPI, authenticates to the MCP Registry with GitHub OIDC, and publishes server.json.

Tech stack

Python 3.10+
MCP Python SDK
PyMuPDF
uv
pytest

License

MIT

Available Tools

12 tools

compare_pdf_pagesA

比较PDF中两个页面的文本差异。

Args: file_path: PDF文件的完整路径 page1: 第一个页码（从1开始） page2: 第二个页码（从1开始）

Returns: 包含以下信息的字典: - page1_chars: 第一页字符数 - page2_chars: 第二页字符数 - common_lines: 相同的行数 - page1_unique_lines: 仅在第一页出现的行数 - page2_unique_lines: 仅在第二页出现的行数 - similarity: 相似度（0-1）

Inputs: page1 (required), page2 (required), file_path (required).

extract_pdf_imagesB

提取PDF中嵌入的图片。

Args: file_path: PDF文件的完整路径 pages: 要提取的页码范围（可选，默认全部页面） min_width: 最小图片宽度，过滤小图片，默认100像素 min_height: 最小图片高度，过滤小图片，默认100像素

Returns: 包含以下信息的字典: - total_images: 图片总数 - images: 图片列表，每个包含: - page: 页码 - image_index: 该页中的图片索引 - width: 宽度 - height: 高度 - format: 图片格式 - image_base64: base64编码的图片数据

Inputs: file_path (required), pages, min_width, min_height.

extract_pdf_linksB

提取PDF中的所有链接（URL和内部跳转）。

Args: file_path: PDF文件的完整路径 pages: 要提取的页码范围（可选，默认全部页面）

Returns: 包含以下信息的字典: - total_links: 链接总数 - external_links: 外部URL链接列表 - internal_links: 内部跳转链接列表

Inputs: file_path (required), pages.

extract_pdf_tablesA

提取PDF中的表格数据。

注意：表格提取依赖PDF的结构，对于复杂或扫描版PDF可能效果不佳。

Args: file_path: PDF文件的完整路径 pages: 要提取的页码范围（可选，默认全部页面）

Returns: 包含以下信息的字典: - total_tables: 表格总数 - tables: 表格列表，每个包含: - page: 页码 - table_index: 该页中的表格索引 - rows: 行数 - cols: 列数 - data: 表格数据（二维数组）

Inputs: file_path (required), pages.

get_pdf_annotationsA

获取PDF中的注释（批注、高亮、下划线等）。

Args: file_path: PDF文件的完整路径 pages: 要提取的页码范围（可选，默认全部页面）

Returns: 包含以下信息的字典: - total_annotations: 注释总数 - annotations: 注释列表，每个包含: - page: 页码 - type: 注释类型 - content: 注释内容 - author: 作者

Inputs: file_path (required), pages.

get_pdf_infoB

获取PDF文件的基本信息。

Args: file_path: PDF文件的完整路径

Returns: 包含以下信息的字典: - page_count: 页数 - title: 标题 - author: 作者 - subject: 主题 - creator: 创建程序 - producer: 生成程序 - creation_date: 创建日期 - modification_date: 修改日期 - file_size: 文件大小(字节) - file_size_mb: 文件大小(MB) - is_encrypted: 是否加密

Inputs: file_path (required).

get_pdf_outlineA

获取PDF的书签/目录结构（大纲）。

Args: file_path: PDF文件的完整路径

Returns: 包含以下信息的字典: - has_outline: 是否有目录 - outline_count: 目录条目数量 - outline: 目录列表，每个元素包含: - level: 层级(1开始) - title: 标题 - page: 页码

Inputs: file_path (required).

get_pdf_page_infoA

获取PDF指定页面的详细信息。

Args: file_path: PDF文件的完整路径 page: 页码（从1开始）

Returns: 包含以下信息的字典: - page_number: 页码 - width: 页面宽度(点) - height: 页面高度(点) - rotation: 旋转角度 - has_text: 是否包含文本 - text_length: 文本长度 - image_count: 图片数量 - link_count: 链接数量

Inputs: page (required), file_path (required).

get_pdf_text_statsA

获取PDF文本的统计信息（字数、字符数、段落数等）。

Args: file_path: PDF文件的完整路径 pages: 要统计的页码范围（可选，默认全部页面）

Returns: 包含以下信息的字典: - total_pages: 总页数 - analyzed_pages: 分析的页数 - total_characters: 总字符数 - total_characters_no_space: 不含空格的字符数 - total_words: 总词数（按空格分割） - total_lines: 总行数 - total_paragraphs: 总段落数 - avg_chars_per_page: 平均每页字符数 - avg_words_per_page: 平均每页词数 - is_likely_scanned: 是否可能是扫描版PDF

Inputs: file_path (required), pages.

read_pdf_as_imagesA

将PDF页面转换为图片(base64编码)返回。适合需要保留原始排版、图表、公式的场景。

Args: file_path: PDF文件的完整路径 pages: 要读取的页码，支持多种格式: - 不传或"all": 所有页面 - "1": 单页 - "1-5": 页码范围 - "1-": 从第1页到末尾 - "-5": 从开头到第5页 - "1,3,5": 指定多页 - "1-3,5,7-9": 混合格式 dpi: 图片分辨率，默认150。72=低质量小文件，150=平衡，300=高清大文件 image_format: 图片格式，"jpeg"(默认，文件小)或"png"(无损，文件大) quality: JPEG压缩质量(1-100)，默认85。仅对jpeg格式有效，值越低文件越小但质量越差 max_total_bytes_mb: 单次调用允许返回的最大图片负载(MB)，默认20

Returns: 图片列表，每个元素包含: - page_number: 页码(从1开始) - image_base64: 图片的base64编码 - width: 图片宽度(像素) - height: 图片高度(像素) - format: 图片格式 - truncated: 是否因大小限制被截断 - warning: 截断或限制提示（可选）

Inputs: file_path (required), dpi, pages, quality, +2 more. Returns: result

read_pdf_as_textA

提取PDF的文本内容。适合纯文本PDF，速度快，消耗token少。

注意：对于扫描版PDF（图片PDF），此方法可能无法提取文本，建议使用read_pdf_as_images。

Args: file_path: PDF文件的完整路径 pages: 要读取的页码，支持多种格式: - 不传或"all": 所有页面 - "1": 单页 - "1-5": 页码范围 - "1-": 从第1页到末尾 - "-5": 从开头到第5页 - "1,3,5": 指定多页 - "1-3,5,7-9": 混合格式 max_pages: 单次调用最多返回的页数，默认50 max_chars: 单次调用最多返回的总字符数，默认200000

Returns: 包含以下信息的字典: - total_pages: 总页数 - extracted_pages: 提取的页码列表 - pages: 每页内容列表，包含page_number和text - full_text: 所有页面的合并文本 - warning: 警告信息（如检测到可能是扫描版PDF或结果被截断）

Inputs: file_path (required), pages, max_chars, max_pages.

search_pdf_textA

在PDF中搜索文本，返回匹配位置和上下文。

Args: file_path: PDF文件的完整路径 query: 搜索关键词 pages: 搜索的页码范围（可选，默认全部页面） max_results: 最大返回结果数，默认50

Returns: 包含以下信息的字典: - query: 搜索关键词 - total_matches: 匹配总数 - pages_with_matches: 有匹配的页码列表 - results: 匹配结果列表，每个包含: - page: 页码 - context: 匹配的上下文文本

Inputs: query (required), file_path (required), pages, max_results.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored 2026-07-29 12:20 across 12 tools

Disambiguation5/5

Each tool has a distinct purpose: metadata, page info, text extraction, image conversion, outline, search, extraction of tables/images/links/annotations, statistics, and comparison. No two tools overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in English (e.g., get_pdf_info, read_pdf_as_images, extract_pdf_tables), using snake_case throughout.

Tool Count5/5

12 tools cover the essential operations for a PDF reader without being excessive. The scope is well-balanced: reading, extraction, search, and analysis.

Completeness5/5

The tool set covers almost all common read-only PDF operations: metadata, page info, text, images, outline, search, tables, links, annotations, statistics, and page comparison. Missing creation or editing, but they are out of scope for a reader.

Resources

Related MCP Connectors

PDF Redaction MCPA
com.pdf-redaction
MCP server for detecting and redacting PII (Personally Identifiable Information) in PDF documents.
File Systems Security
23
https://api.pdf-redaction.com/mcp/
PDF to Markdown (pdf2md.dev)
dev.pdf2md
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
AI & Machine Learning Image & Video Processing
2
https://pdf2md.dev/api/v2/mcp
mcp-server
com.pdfgate
MCP server for the PDFGate API. Generate PDFs, manage documents and handle e-signatures.
Documentation Access File Systems
1
https://mcp.pdfgate.com/server
pdfrenderA
dev.pdfrender
HTML and CSS to PDF MCP server with page headers, footers and page numbers. No headless browser.
Workplace & Productivity
11
https://api.pdfrender.dev/mcp/

Related MCP Servers

PDF Extraction MCP Server
File Systems Text Summarization
xraywu
F
license
C
quality
D
maintenance
An MCP server that provides a tool to extract text content from local PDF files, supporting both standard PDF reading and OCR capabilities with optional page selection.
Updated a year ago (2025-05-31 11:21 UTC)
1
33
-
MCP PDF Server
Image & Video Processing Text Summarization Multimedia Processing
DeepSeekMine
F
license
Not graded
quality
D
maintenance
A PDF processing server that extracts text via normal parsing or OCR, and retrieves images from PDF files through the MCP protocol with a built-in web debugger.
Updated 2 years ago (2025-04-28 23:56 UTC)
36
-
PDF Reader MCP Server
Documentation Access File Systems
averagejoeslab
F
license
Not graded
quality
D
maintenance
An MCP server that provides comprehensive PDF processing capabilities including text extraction, image extraction, table detection, annotation extraction, metadata retrieval, page rendering, and document structure analysis.
Updated 9 months ago (2026-02-07 21:54 UTC)
-
mcp-pdf-tools
Documentation Access Research & Data Text Summarization
seraphinerenard
A
license
A
quality
Not graded
maintenance
An MCP server that enables users to read, search, and analyze PDF documents. It provides tools for extracting text, viewing metadata, searching content with context, and generating word statistics.
Updated 9 months ago (2026-01-29 18:31 UTC)
5
-

pdf-reader-mcp

Package name

Features

Quick start

MCP client configuration

Common usage

Limits and behavior

Development

Release

Tech stack

License

Available Tools

Tool Schema Changelog

TDQS

Resources

Related MCP Connectors

Related MCP Servers

PDF Extraction MCP Server

MCP PDF Server

PDF Reader MCP Server

mcp-pdf-tools