Pdf Reader
一个基于 Model Context Protocol (MCP) 的 PDF 文件读取服务器,为 AI 助手(如 Claude)提供强大的 PDF 文件处理能力。
Installation
npx mcp-pdf-readerAsk AI about Pdf Reader
Powered by Claude · Grounded in docs
I know everything about Pdf Reader. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
贡献指南
欢迎贡献代码!请遵循以下步骤:
- Fork 本仓库
- 创建功能分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
许可证
本项目采用 MIT 许可证 - 详见 LICENSE 文件
作者
dongchengcheng
致谢
- Model Context Protocol - 提供协议标准
- MCP SDK - 官方 SDK
- pdf-parse - PDF 解析库
更新日志
v1.0.0 (2024)
- 初始版本发布
- 实现基础 PDF 读取功能
- 添加元数据获取
- 实现文本搜索功能
- 解决 ESM/CommonJS 兼容性问题
联系方式
如有问题或建议,请通过以下方式联系:
- 提交 Issue
- 发起 Discussion
