PDF Reader

pdf-reader-mcp

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

一个专注于 PDF 的 MCP 服务，用于从 PDF 文件中提取文本、渲染页面、表格、链接、批注、目录、元数据和文本统计信息。

包名称

• GitHub 仓库：pdf-reader-mcp
• MCP Registry 名称：io.github.Xvvln/pdf-reader-mcp
• PyPI 包：pdf-insight-mcp
• CLI 命令：pdf-reader-mcp 和 pdf-insight-mcp

pdf-reader-mcp 是项目名称。由于 PyPI 上的 pdf-reader-mcp 包名称不可用，因此该项目以 pdf-insight-mcp 的名称发布到 PyPI。

功能

工具	功能说明
get_pdf_info	读取文档元数据、页数、文件大小和加密状态。
read_pdf_as_text	从选定页面提取文本，并限制页面数和字符数。
read_pdf_as_images	将选定页面渲染为 Base64 编码的图片。
get_pdf_outline	读取书签和目录条目。
search_pdf_text	搜索文本并返回每个匹配项所在页面的上下文。
extract_pdf_tables	在 PyMuPDF 能够检测到结构化表格时提取这些表格。
extract_pdf_images	提取嵌入的 PDF 图片。
get_pdf_page_info	检查单个页面的大小、文本、图片、链接和旋转角度。
extract_pdf_links	提取外部 URL 和内部页面跳转链接。
get_pdf_annotations	读取批注、高亮和批注元数据。
get_pdf_text_stats	计算文本、行、段落和扫描件可能性统计信息。
compare_pdf_pages	比较两个页面之间的文本相似度。

快速开始

如果尚未安装 uv，请先安装：

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

直接从 PyPI 运行服务：

uvx pdf-insight-mcp

或者先安装：

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

MCP 客户端配置

使用已发布到 PyPI 的包：

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

开发时使用本地检出版本：

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

将 /absolute/path/to/pdf-reader-mcp 替换为此仓库在你计算机上的绝对路径。

常见用法

让 MCP 客户端使用 PDF 的绝对路径调用工具。请求示例：

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.

对于大型 PDF，请先使用较小的页面范围。对于扫描件或对版式敏感的 PDF，请使用 read_pdf_as_images，并指定较小的 pages 范围和适中的 dpi。

限制和行为

• read_pdf_as_text 默认最多处理 50 页，并返回最多 200000 个字符。
• read_pdf_as_images 会拒绝超过 20 页的请求。
• read_pdf_as_images 默认将图片总负载限制在约 20 MB。
• extract_pdf_images 最多返回 20 张嵌入的图片，但会报告实际检测到的总数。
• 除非加密 PDF 无需密码即可访问，否则会拒绝处理。
• 扫描版 PDF 可能几乎没有或完全没有可提取的文本。必要时，请在本服务之外使用图片渲染或 OCR。

开发

安装依赖：

uv sync --extra dev

运行测试：

uv run pytest -q

构建包：

uv build
uvx twine check dist/*

运行本地服务：

uv run pdf-reader-mcp

发布

通过 GitHub Actions 发布版本。

首次发布前，请使用以下信息配置 PyPI Trusted Publishing：

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

然后，在 pyproject.toml 和 server.json 中更新版本，提交更改并推送版本标签以发布：

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

Publish 工作流会运行测试、构建 Python 包、发布到 PyPI、使用 GitHub OIDC 向 MCP Registry 进行身份验证，并发布 server.json。

技术栈

• Python 3.10+
• MCP Python SDK
• PyMuPDF
• uv
• pytest

许可证

MIT