MCP 服务器

mcp-pdf-reader

A Model Context Protocol server that enables AI assistants to read PDF files, extract text, retrieve metadata, read specific pages, and search within PDFs.

README

MCP PDF Reader

一个基于 Model Context Protocol (MCP) 的 PDF 文件读取服务器，为 AI 助手（如 Claude）提供强大的 PDF 文件处理能力。

功能特性

📖 读取 PDF 文件：提取 PDF 文件的完整文本内容
📊 获取 PDF 元数据：获取文件信息（标题、作者、页数、创建日期等）
📄 按页读取：支持读取指定页面范围的内容
🔍 文本搜索：在 PDF 中搜索特定文本，支持大小写敏感搜索
⚡ 稳定可靠：使用 CommonJS 方式加载 pdf-parse，避免 ESM 兼容性问题
🛡️ 错误处理：完善的错误处理和用户友好的错误信息

安装

前置要求

Node.js 16.0 或更高版本
npm 或 yarn

安装步骤

克隆仓库：

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

安装依赖：

npm install

构建项目：

npm run build

配置使用

在 Claude Desktop 中使用

在 Claude Desktop 的配置文件中添加以下配置：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pdf-reader": {
      "command": "node",
      "args": ["/path/to/mcp-pdf-reader/build/index.js"]
    }
  }
}

将 /path/to/mcp-pdf-reader 替换为实际的项目路径。

重启 Claude Desktop 后，即可在对话中使用 PDF 读取功能。

可用工具

1. read_pdf

读取 PDF 文件的完整文本内容。

参数：

file_path (string, 必需): PDF 文件的路径

使用示例：

请读取文件 /Users/xxx/Documents/report.pdf

返回：

PDF 文件的完整文本内容
总页数信息

2. get_pdf_info

获取 PDF 文件的元数据信息。

参数：

file_path (string, 必需): PDF 文件的路径

返回信息：

文件路径、文件名、文件大小
页数
标题、作者、创建者、制作者
创建日期、修改日期
文本字符数、文本行数

使用示例：

获取 /Users/xxx/Documents/report.pdf 的详细信息

3. read_pages

读取 PDF 文件的特定页面范围。

参数：

file_path (string, 必需): PDF 文件的路径
start_page (number, 必需): 起始页码（从 1 开始）
end_page (number, 可选): 结束页码（从 1 开始）

使用示例：

读取文件 /Users/xxx/Documents/report.pdf 的第 5 到第 10 页

4. search_in_pdf

在 PDF 文件中搜索特定文本。

参数：

file_path (string, 必需): PDF 文件的路径
search_text (string, 必需): 要搜索的文本
case_sensitive (boolean, 可选): 是否大小写敏感，默认为 false

使用示例：

在文件 /Users/xxx/Documents/report.pdf 中搜索 "重要数据"

返回：

匹配项的总数
包含匹配文本的行（最多显示前 10 个）
每个匹配项的行号

开发

项目结构

mcp-pdf-reader/
├── src/
│   └── index.ts        # 主服务器代码
├── build/              # 编译后的 JavaScript 文件
├── package.json        # 项目配置
├── tsconfig.json       # TypeScript 配置
├── .gitignore         # Git 忽略文件
└── README.md          # 本文档

开发命令

npm run build - 构建项目
npm run watch - 监视文件变化并自动重新构建
npm run inspector - 运行 MCP 检查器进行调试

技术实现

ESM 与 CommonJS 兼容性处理

项目使用 ESM 模块系统，但通过 createRequire 方法加载 CommonJS 模块：

import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const pdf = require('pdf-parse');

这种方式确保了与 pdf-parse 库的完美兼容。

错误处理机制

文件存在性检查
PDF 文件格式验证
页码范围验证
详细的错误信息返回

性能优化

搜索结果限制（最多显示前 10 个匹配项）
大文件处理优化
内存友好的流式处理

技术栈

TypeScript: 类型安全的开发语言
@modelcontextprotocol/sdk: MCP 官方 SDK
pdf-parse: PDF 文件解析库
canvas: PDF 渲染支持（pdf-parse 的依赖）

限制和注意事项

文本提取限制：目前只支持文本内容提取，不支持：
- 图片提取
- 表格结构保持
- 复杂格式保留
页面分离：由于 pdf-parse 库的限制，按页读取功能目前返回的是全文内容
搜索结果：为避免输出过长，搜索结果最多显示前 10 个匹配项
文件大小：处理超大 PDF 文件时可能需要更多内存

故障排除

常见问题

Canvas 编译错误
- 确保系统安装了必要的编译工具
- macOS: 安装 Xcode Command Line Tools
- Windows: 安装 windows-build-tools
- Linux: 安装 build-essential
PDF 解析失败
- 检查 PDF 文件是否损坏
- 确认文件路径是否正确
- 验证文件权限
MCP 连接失败
- 检查配置文件路径是否正确
- 确保构建后的文件存在
- 重启 Claude Desktop