MCP PDF Reader

项目简介

MCP PDF Reader 是一个专业的 PDF 文档处理工具通过 Model Context Protocol (MCP) 为 AI 应用提供强大的 PDF 文本提取搜索OCR 识别等功能它能够智能识别 PDF 类型自动选择最佳处理策略为用户提供高效便捷的文档处理体验

核心优势

• ** 智能识别**自动判断 PDF 类型文本型/扫描型选择最佳处理方案
• ** 强大搜索**支持正则表达式全字匹配大小写敏感搜索
• ** 完整元数据**提取作者标题创建日期等 13 项元数据
• ** 多语言 OCR**支持中文英文日文韩文等 10 种语言识别
• ** 高性能**令牌缓存机制智能错误处理并发保护使用文件缓存重复读取pdf文件不消耗API调用
• ** 安全可靠**文件大小限制路径验证错误隔离

快速开始

1. 安装依赖

npm install

2. 配置 MCP 服务器

在你的 AI 客户端如 Cursor配置文件中添加

{
  "mcpServers": {
    "pdf-reader": {
      "command": "node",
      "args": ["你的项目路径/mcp_pdf_reader/index.js"]
    }
  }
}

3. 可选配置百度 OCR

1. 访问https://console.bce.baidu.com/ai/#/ai/ocr/overview/index
2. 创建应用每个月大约 1000-5000 页的免费额度获取 API Key 和 Secret Key

如果需要使用 OCR 功能有两种配置方式

方式一环境变量配置推荐

设置环境变量

# Windows
set BAIDU_OCR_API_KEY=你的API密钥
set BAIDU_OCR_SECRET_KEY=你的Secret密钥

# Linux/Mac
export BAIDU_OCR_API_KEY=你的API密钥
export BAIDU_OCR_SECRET_KEY=你的Secret密钥

方式二配置文件配置

也可以直接在 Cursor 配置文件中配置

{
  "mcpServers": {
    "pdf-reader": {
      "command": "node",
      "args": ["你的项目路径/mcp_pdf_reader/index.js"],
      "env": {
        "BAIDU_OCR_API_KEY": "你的API密钥",
        "BAIDU_OCR_SECRET_KEY": "你的Secret密钥"
      }
    }
  }
}

4. 重启客户端

重启 Cursor 或你的 MCP 客户端即可开始使用

功能特性

核心工具

智能特性

• 自动类型检测智能识别 PDF 是文本型还是扫描型
• 自动降级策略文本提取失败时自动切换到 OCR
• 成本优化优先使用免费的文本提取需要时才调用 OCR
• 质量保证三重文本质量检查字符密度行数空白率
• 图像检测警告提醒可能包含的重要图像内容
• 智能缓存OCR 结果缓存避免重复识别
• 批量处理支持多页批量处理和分页处理

技术栈

核心依赖

{
  "@modelcontextprotocol/sdk": "^1.12.1",  // MCP 协议框架
  "axios": "^1.12.2",                     // HTTP 请求库
  "pdf-parse": "^1.1.1",                  // PDF 文本解析
  "pdf-to-png-converter": "^3.10.0",      // PDF 转图片工具
  "pdf-lib": "^1.17.1",                   // PDF 文档操作库
  "zod": "^3.25.61"                       // 参数验证库
}

系统要求

• Node.js: 18.0.0 或更高版本
• 内存: 至少 512MB 可用内存处理大文件需要更多
• 磁盘: 足够的临时存储空间

使用指南

推荐工具read-pdf-smart

最智能的 PDF 阅读工具适合 99% 的使用场景

参数说明

使用示例

// 示例 1: 读取整个 PDF自动选择最佳方式
{
  "file": "D:\\Documents\\report.pdf"
}

// 示例 2: 只读取前 3 页
{
  "file": "D:\\Documents\\report.pdf",
  "pages": "1-3"
}

// 示例 3: 只读取第一页和最后一页
{
  "file": "D:\\Documents\\book.pdf",
  "pages": "first"
}

工具read-pdf

基础文本提取工具适用于文本型 PDF

参数说明

使用示例

// 基本提取
{
  "file": "D:\\Documents\\report.pdf"
}

// 仅提取第 5-10 页清理文本不包含元数据
{
  "file": "D:\\Documents\\report.pdf",
  "pages": "5-10",
  "clean_text": true,
  "include_metadata": false
}

工具search-pdf

PDF 全文搜索工具支持高级搜索选项

参数说明

使用示例

// 不区分大小写的搜索
{
  "file": "D:\\Documents\\manual.pdf",
  "query": "API"
}

// 全字匹配 + 区分大小写
{
  "file": "D:\\Documents\\code.pdf",
  "query": "const",
  "case_sensitive": true,
  "whole_word": true
}

工具pdf-metadata

元数据提取工具获取 PDF 文件信息不读取文本内容

提取的元数据

• 文件名文件大小页面数
• 作者标题主题
• 创建者生成器软件
• 创建日期修改日期
• 关键词
• 是否加密
• PDF 版本

使用示例

{
  "file": "D:\\Documents\\thesis.pdf"
}

OCR 工具

ocr-pdf-auto-legacy推荐

自动 OCR 识别工具从环境变量读取密钥更方便

参数说明

支持的语言类型

• CHN_ENG - 中英文混合默认
• ENG - 英文
• JAP - 日文
• KOR - 韩文
• FRE - 法文
• SPA - 西班牙文
• POR - 葡萄牙文
• GER - 德文
• ITA - 意大利文
• RUS - 俄文

使用示例

// 识别第一页默认
{
  "file": "D:\\Documents\\invoice.pdf"
}

// 识别所有页面最多 10 页
{
  "file": "D:\\Documents\\contract.pdf",
  "pages": "all",
  "detect_direction": true,
  "detect_language": true
}

// 只识别最后一页
{
  "file": "D:\\Documents\\report.pdf",
  "pages": "last"
}

配置说明

系统要求

• Node.js: 18.0.0 或更高版本
• 内存: 至少 512MB 可用内存处理大文件需要更多
• 磁盘: 足够的临时存储空间

安装步骤

1. 克隆或下载项目

git clone https://github.com/your-repo/mcp-pdf-reader.git
cd mcp-pdf-reader

2. 安装依赖

npm install

3. 配置 Cursor或其他 MCP 客户端

编辑 Cursor 配置文件添加 MCP 服务器配置

{
  "mcpServers": {
    "pdf-reader": {
      "command": "node",
      "args": ["你的完整项目路径/mcp_pdf_reader/index.js"]
    }
  }
}

4. 可选配置百度 OCR

获取百度 OCR API 密钥

1. 访问 百度智能云控制台
2. 创建应用并选择"文字识别 OCR"服务
3. 在应用管理页面获取 API Key 和 Secret Key

配置环境变量

方式 1永久配置推荐

Windows 系统设置

1. 右键"此电脑" "属性" "高级系统设置"
2. 点击"环境变量"
3. 在"用户变量"中添加
   • BAIDU_OCR_API_KEY = 你的 API Key
   • BAIDU_OCR_SECRET_KEY = 你的 Secret Key

方式 2临时配置

# Windows CMD
set BAIDU_OCR_API_KEY=your_api_key
set BAIDU_OCR_SECRET_KEY=your_secret_key

# Windows PowerShell
$env:BAIDU_OCR_API_KEY="your_api_key"
$env:BAIDU_OCR_SECRET_KEY="your_secret_key"

# Linux/Mac
export BAIDU_OCR_API_KEY=your_api_key
export BAIDU_OCR_SECRET_KEY=your_secret_key

5. 重启客户端

重启 Cursor 或你的 MCP 客户端以加载配置

核心模块说明

• MCP 服务器: 基于 @modelcontextprotocol/sdk 实现
• PDF 处理: 集成 pdf-parse 和 pdf-lib 进行文本提取
• OCR 识别: 集成百度 OCR API支持多语言识别
• 缓存系统: 智能缓存机制提升处理效率
• 错误处理: 完善的错误处理和用户友好的错误信息

高级配置

文件大小限制

默认最大文件大小50MB

修改限制在 index.js 中

if (stats.size > 50 * 1024 * 1024) { // 修改这里的数值
    throw new Error(`文件过大: ${(stats.size / 1024 / 1024).toFixed(2)}MB最大支持 50MB`);
}

OCR 处理页数限制

默认最多处理10 页

修改限制在 index.js 中

if (pageNumbers.length > 10) { // 修改这里的数值
    pageNumbers = pageNumbers.slice(0, 10);
}

文本质量检查阈值

可以调整质量判断规则在 index.js 中

// 每页最少字符数
if (text.length < 50 * pageCount) return 'poor';

// 字母数字占比最低要求
if (ratio < 0.3) return 'poor';

使用技巧

如何选择合适的工具

 你的需求是什么                                              

                  
    
                              
读取 PDF      搜索内容      查看信息
                              
                              
    
不确定类型   文本搜索    元数据   
             
                              
                              
           search-pdf    pdf-metadata
         
    
             
  文本型   扫描型
             
             
 read-pdf  ocr-pdf-auto


   read-pdf-smart       推荐自动识别
   智能选择        

最佳实践

1. 优先使用 read-pdf-smart

//  推荐让工具自动判断
{
  "file": "unknown-document.pdf"
}

2. 处理大文件时指定页码范围

//  推荐只处理需要的页面
{
  "file": "large-book.pdf",
  "pages": "1-10"  // 只读前 10 页
}

3. OCR 识别时使用正确的语言类型

//  推荐指定正确的语言
{
  "file": "japanese-doc.pdf",
  "language_type": "JAP"  // 日文文档
}

4. 搜索时使用合适的选项

//  推荐搜索代码关键字时使用全字匹配
{
  "file": "code-documentation.pdf",
  "query": "const",
  "whole_word": true  // 避免匹配到 "constant"
}

开发指南

添加新工具

// 在 index.js 中添加
server.tool(
    "your-new-tool",
    {
        param1: z.string().describe("参数说明"),
        param2: z.number().optional()
    },
    async ({ param1, param2 }) => {
        try {
            // 你的处理逻辑
            return {
                content: [{
                    type: "text",
                    text: "处理结果"
                }]
            };
        } catch (error) {
            return {
                content: [{
                    type: "text",
                    text: `错误: ${error.message}`
                }]
            };
        }
    }
);

调试技巧

由于 MCP 协议的限制不能直接使用 console.log建议

// 写入日志文件
import fs from 'fs';
fs.appendFileSync('debug.log', `[${new Date().toISOString()}] ${message}\n`);

贡献指南

我们欢迎所有形式的贡献

贡献方向

• Bug 修复修复已知问题
• 新功能添加新的 PDF 处理功能
• 文档改进完善使用文档和示例
• 性能优化提升处理速度和内存使用
• 测试添加单元测试和集成测试
• 国际化支持更多语言

代码规范

• 使用 ES6+ 语法
• 添加 详细的中文注释
• 遵循 异步/等待 模式
• 包含 错误处理
• 提供 JSDoc 文档

许可证

本项目采用 MIT 许可证详见 LICENSE 文件

致谢

• Model Context Protocol - MCP 协议框架
• pdf-parse - PDF 解析库
• pdf-to-png-converter - PDF 转图片工具
• pdf-lib - PDF 文档操作库
• Baidu AI - OCR 服务提供商
• 所有贡献者和用户的支持

[{'mcpServers': {'pdf-reader': {'args': ['你的项目路径/mcp_pdf_reader/index.js'], 'command': 'node'}}}, {'mcpServers': {'pdf-reader': {'args': ['你的项目路径/mcp_pdf_reader/index.js'], 'command': 'node', 'env': {'BAIDU_OCR_API_KEY': '你的API密钥', 'BAIDU_OCR_SECRET_KEY': '你的Secret密钥'}}}}, {'mcpServers': {'pdf-reader': {'args': ['你的完整项目路径/mcp_pdf_reader/index.js'], 'command': 'node'}}}]