MCP PDF Reader

🚀 基于 Model Context Protocol 的智能 PDF 处理服务器

功能强大 · 易于使用 · 智能识别

📖 项目简介

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

访问：https://console.bce.baidu.com/ai/#/ai/ocr/overview/index
创建应用，每个月大约 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 客户端，即可开始使用！

✨ 功能特性

🛠️ 核心工具

| 功能 | 工具名称 | 说明 | 推荐指数 | |------|----------|------|----------| | 智能阅读 | read-pdf-smart | 自动识别文本/扫描型 PDF，选择最佳策略 | ⭐⭐⭐⭐⭐ | | 文本提取 | read-pdf | 从文本型 PDF 提取内容，支持页码范围 | ⭐⭐⭐⭐ | | 内容搜索 | search-pdf | 全文搜索，支持正则、大小写、全字匹配 | ⭐⭐⭐⭐ | | 元数据提取 | pdf-metadata | 获取 PDF 文件的完整元数据信息 | ⭐⭐⭐ | | OCR 识别 | ocr-pdf-legacy | 百度 OCR 识别（手动传递密钥） | ⭐⭐⭐ | | 自动 OCR | ocr-pdf-auto-legacy | 百度 OCR 识别（自动读取环境变量） | ⭐⭐⭐⭐ |

🎯 智能特性

自动类型检测：智能识别 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% 的使用场景。

参数说明

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | file | string | 必填 | PDF 文件的完整路径 | | pages | string | 'all' | 页码范围（支持 'first', 'last', 'all', '1-5', '1,3,5'） | | language_type | enum | 'CHN_ENG' | OCR 语言类型（需要时使用） |

使用示例

// 示例 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 | string | 必填 | PDF 文件路径 | | pages | string | 'all' | 页码范围（如 '1-5', '1,3,5', 'all'） | | include_metadata | boolean | true | 是否包含 PDF 元数据 | | clean_text | boolean | false | 是否清理和规范化文本 |

使用示例

// 基本提取
{
  "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 | string | 必填 | PDF 文件路径 | | query | string | 必填 | 要搜索的文本 | | case_sensitive | boolean | false | 是否区分大小写 | | whole_word | boolean | false | 是否全字匹配 |

使用示例

// 不区分大小写的搜索
{
  "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 识别工具（从环境变量读取密钥，更方便）。

参数说明

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | file | string | 必填 | PDF 文件路径 | | pages | string | 'first' | 页码范围（支持 'first', 'last', 'all', '1-5', '1,3,5'） | | language_type | enum | 'CHN_ENG' | 语言类型 | | detect_direction | boolean | false | 是否检测方向 | | detect_language | boolean | false | 是否检测语言 |

支持的语言类型

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 密钥：

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

配置环境变量：

方式 1：永久配置（推荐）

Windows 系统设置：

右键"此电脑" → "属性" → "高级系统设置"
点击"环境变量"
在"用户变量"中添加：
- 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 服务提供商
所有贡献者和用户的支持！

如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！

MCP PDF Reader

📖 项目简介

🎯 核心优势

🚀 快速开始

1. 安装依赖

2. 配置 MCP 服务器

3. （可选）配置百度 OCR

方式一：环境变量配置（推荐）

方式二：配置文件配置

4. 重启客户端

✨ 功能特性

🛠️ 核心工具

🎯 智能特性

🛠️ 技术栈

核心依赖

系统要求

📚 使用指南

🌟 推荐工具：read-pdf-smart

参数说明

使用示例

📄 工具：read-pdf

参数说明

使用示例

🔍 工具：search-pdf

参数说明

使用示例

📊 工具：pdf-metadata

提取的元数据

使用示例

🖼️ OCR 工具

ocr-pdf-auto-legacy（推荐）

参数说明

支持的语言类型

使用示例

⚙️ 配置说明

系统要求

安装步骤

1. 克隆或下载项目

2. 安装依赖

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

4. （可选）配置百度 OCR

5. 重启客户端

核心模块说明

🔧 高级配置

文件大小限制

OCR 处理页数限制

文本质量检查阈值

💡 使用技巧

如何选择合适的工具？

最佳实践

1. 优先使用 read-pdf-smart

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

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

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

🔬 开发指南

添加新工具

调试技巧

🤝 贡献指南

贡献方向

代码规范

📄 许可证

🙏 致谢

安装包 （如果需要）

Cursor 配置 (mcp.json)

1. 优先使用 `read-pdf-smart`

安装包（如果需要）