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.

<!-- mcp-name: io.github.Xvvln/pdf-reader-mcp -->

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.

Features

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