mcp_pdf_reader

@3351163616/mcp_pdf_reader

0 Stars 28 次浏览 3351163616 更新于 2026-08-23

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

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

服务介绍

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

基础文本提取工具适用于文本型 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 服务配置

服务介绍

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. 搜索时使用合适的选项

开发指南

添加新工具

调试技巧

贡献指南

贡献方向

代码规范

许可证

致谢

相关 MCP 服务

开源版 与 企业版

企业版（含 FDE 交付）

技能定制开发服务

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

开源版与企业版