STARWARCLOUD STARWAR.AI
返回市场
PDF阅读器

PDF阅读器

作者：labeveryday8 星标更新：2025-06-17
安装使用来源：spider==github.com

项目介绍

MCP PDF阅读器服务器（Python + FastMCP）

这是一个使用FastMCP构建的强大模型上下文协议（MCP）服务器，提供全面的PDF处理功能，包括文本提取、图像提取以及用于读取图像内文字的OCR。

功能

  • 文本提取：从PDF页面中提取文本内容
  • 图像提取：从PDF文件中提取所有图像
  • OCR能力：使用Tesseract OCR从图像中读取文本
  • 综合分析：获取详细的PDF结构和元数据
  • 页码范围支持：处理特定的页码范围
  • 多种语言：支持多种语言的OCR

预备条件

系统依赖

Tesseract OCR

你需要在系统上安装Tesseract OCR：

Ubuntu/Debian:

sudo apt update
sudo apt install tesseract-ocr tesseract-ocr-eng

macOS:

brew install tesseract

Windows:

  1. 下载自：https://github.com/UB-Mannheim/tesseract/wiki
  2. 安装并添加到PATH
  3. 或者使用：conda install -c conda-forge tesseract

其他语言包（可选）

# 多种语言
sudo apt install tesseract-ocr-fra tesseract-ocr-deu tesseract-ocr-spa

安装

使用UV快速启动

  1. 安装UV（如果尚未安装）：
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  1. 克隆/创建项目：
mkdir mcp-pdf-reader-server
cd mcp-pdf-reader-server
  1. 使用UV初始化并安装：
# 复制文件（pdf_reader_server.py 和 pyproject.toml）
# 然后安装依赖项
uv sync
  1. 验证安装：
uv run python -c "import pytesseract; print(pytesseract.get_tesseract_version())"

替代方案：手动设置

如果你更喜欢传统的设置方式：

  1. 创建虚拟环境：
python -m venv .venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate
  1. 安装依赖项：
pip install fastmcp PyMuPDF pytesseract Pillow

使用方法

运行服务器

使用UV：

uv run python pdf_reader_server.py

或者如果你已经激活了环境：

python pdf_reader_server.py

服务器将启动并监听标准输入/输出上的MCP请求。

可用工具

1. read_pdf_text

从PDF页面中提取文本内容。

参数：

  • file_path（字符串，必需）：PDF文件路径
  • page_range（对象，可选）：包含起始和结束页码的字典

示例：

{
  "file_path": "/path/to/document.pdf",
  "page_range": {"start": 1, "end": 5}
}

2. extract_pdf_images

从PDF文件中提取所有图像。

参数：

  • file_path（字符串，必需）：PDF文件路径
  • output_dir（字符串，可选）：保存图像的目录
  • page_range（对象，可选）：要处理的页码范围

示例：

{
  "file_path": "/path/to/document.pdf",
  "output_dir": "/path/to/images/",
  "page_range": {"start": 1, "end": 3}
}

3. read_pdf_with_ocr

使用OCR从常规文本和图像中提取文本。

参数：

  • file_path（字符串，必需）：PDF文件路径
  • page_range（对象，可选）：要处理的页码范围
  • ocr_language（字符串，可选）：OCR语言代码（默认："eng"）

示例：

{
  "file_path": "/path/to/document.pdf",
  "ocr_language": "eng+fra",
  "page_range": {"start": 1, "end": 10}
}

支持的OCR语言：

  • eng - 英语
  • fra - 法语
  • deu - 德语
  • spa - 西班牙语
  • eng+fra - 多种语言

4. get_pdf_info

获取关于PDF的详细元数据和统计信息。

参数：

  • file_path（字符串，必需）：PDF文件路径

5. analyze_pdf_structure

分析PDF的结构和内容分布。

参数：

  • file_path（字符串，必需）：PDF文件路径

使用Claude Desktop配置

使用UV

在你的claude_desktop_config.json中添加以下内容：

{
  "mcpServers": {
    "pdf-reader": {
      "command": "uv",
      "args": ["run", "python", "/path/to/your/pdf_reader_server.py"],
      "cwd": "/path/to/your/mcp-pdf-reader-server"
    }
  }
}

使用虚拟环境

{
  "mcpServers": {
    "pdf-reader": {
      "command": "/path/to/your/.venv/bin/python",
      "args": ["/path/to/your/pdf_reader_server.py"]
    }
  }
}

系统Python

{
  "mcpServers": {
    "pdf-reader": {
      "command": "python",
      "args": ["/path/to/your/pdf_reader_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/your/.venv/lib/python3.x/site-packages"
      }
    }
  }
}

示例响应

文本提取响应

{
  "success": true,
  "file_path": "/path/to/document.pdf",
  "pages_processed": "1-3",
  "total_pages": 10,
  "pages_text": [
    {
      "page_number": 1,
      "text": "第一页内容...",
      "word_count": 125
    }
  ],
  "combined_text": "所有文本组合...",
  "total_word_count": 1250,
  "total_character_count": 8750
}

OCR响应

{
  "success": true,
  "file_path": "/path/to/document.pdf",
  "pages_processed": "1-2",
  "ocr_language": "eng",
  "pages_data": [
    {
      "page_number": 1,
      "text": "来自PDF的常规文本...",
      "ocr_text": "从图像中提取的文本...",
      "images_with_text": [
        {
          "image_index": 1,
          "ocr_text": "来自图像1的文本",
          "confidence": "高"
        }
      ],
      "combined_text": "组合文本和OCR...",
      "text_word_count": 100,
      "ocr_word_count": 25
    }
  ],
  "summary": {
    "total_text_word_count": 200,
    "total_ocr_word_count": 50,
    "combined_word_count": 250,
    "images_processed": 3
  },
  "all_text_combined": "所有提取的文本..."
}

性能考虑

OCR性能

  • 对于大图，OCR处理可能较慢
  • 考虑处理较小的页码范围以获得更快的结果
  • 小于50x50像素的图像将自动跳过

内存使用

  • 包含大量图像的大PDF可能会消耗大量内存
  • 服务器按顺序处理页面以管理内存使用
  • 提取的图像将保存到磁盘以减少内存压力

优化建议

  1. 使用页码范围处理大型文档
  2. 指定输出目录进行图像提取以避免临时文件堆积
  3. 选择适当的OCR语言以提高准确性和速度
  4. 预处理图像如果OCR质量较差（考虑添加OpenCV）

故障排除

常见问题

  1. 未找到Tesseract：

    TesseractNotFoundError: tesseract未安装
    • 安装Tesseract OCR系统包
    • 确保它在你的PATH中

  2. 权限错误：

    • 确保Python进程有读取PDF文件的权限
    • 确保有写入输出目录的权限

  3. OCR结果差：

    • 尝试不同的OCR语言代码
    • 考虑图像预处理
    • 检查图像是否足够高分辨率

  4. 内存错误：

    • 处理较小的页码范围
    • 关闭其他应用程序
    • 考虑增加可用RAM

调试模式

使用UV运行带有调试日志：

PYTHONUNBUFFERED=1 uv run python pdf_reader_server.py

或者使用普通Python：

PYTHONUNBUFFERED=1 python pdf_reader_server.py

测试OCR

直接测试Tesseract：

tesseract --list-langs
tesseract image.png output.txt

依赖项

  • fastmcp：现代MCP服务器框架
  • PyMuPDF：快速的PDF处理和渲染
  • pytesseract：Tesseract OCR的Python封装
  • Pillow：图像处理库
  • tesseract-ocr：系统OCR引擎

高级功能

自定义OCR配置

你可以在代码中修改OCR配置：

ocr_text = pytesseract.image_to_string(
    pil_image, 
    lang=ocr_language,
    config='--psm 6 -c tessedit_char_whitelist=0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz '
)

图像预处理

为了获得更好的OCR结果，可以考虑添加图像预处理：

# 添加到需求：opencv-python, numpy
import cv2
import numpy as np

# 预处理示例
def preprocess_image(image):
    gray = cv2.cvtColor(np.array(image), cv2.COLOR_RGB2GRAY)
    thresh = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY | cv2.THRESH_OTSU)[1]
    return Image.fromarray(thresh)

贡献

  1. 分叉仓库
  2. 创建功能分支
  3. 为新功能添加测试
  4. 提交拉取请求

许可证

MIT许可证 - 详情见LICENSE文件。