📄 @sylphx/pdf-reader-mcp

面向 AI 代理的生产级 PDF 处理服务器

并行处理速度提升 5–10 倍 • 按 Y 坐标内容排序 • 测试覆盖率 94%+ • 103 项测试全部通过

🚀 概述

PDF Reader MCP 是一个生产就绪的模型上下文协议服务器，为 AI 代理提供企业级 PDF 处理能力。以无与伦比的性能和可靠性提取文本、图像和元数据。

问题所在：

// 传统 PDF 处理方式
- 逐页处理（速度慢）
- 内容无自然顺序
- 路径处理复杂
- 错误隔离性差

解决方案：

// PDF Reader MCP
- 并行处理速度提升 5–10 倍 ⚡
- 基于 Y 坐标的排序 📐
- 灵活的路径支持（绝对/相对）🎯
- 每页独立错误恢复 🛡️
- 测试覆盖率 94%+ ✅

结果：可扩展的生产级 PDF 处理方案。

⚡ 核心特性

性能

• 🚀 速度提升 5–10 倍，自动并行化
• ⚡ 12,933 ops/sec 错误处理，5,575 ops/sec 文本提取
• 💨 多核利用，可在几秒钟内处理 50 页 PDF
• 📦 轻量级，依赖极少

开发者体验

• 🎯 路径灵活性 - 支持绝对路径和相对路径，兼容 Windows 和 Unix（v1.3.0）
• 🖼️ 智能排序 - 基于 Y 坐标的排序保留文档布局
• 🛡️ 类型安全 - 完全 TypeScript，启用严格模式
• 📚 实战检验 - 103 项测试，覆盖率 94%+，函数覆盖率 98%+
• 🎨 简单 API - 单一工具优雅地完成所有操作

📊 性能基准测试

生产环境实测表现：

并行处理加速效果

基准测试结果因 PDF 复杂度和系统资源而异。

📦 安装

Claude Code

claude mcp add pdf-reader -- npx @sylphx/pdf-reader-mcp

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"]
    }
  }
}

VS Code

code --add-mcp '{"name":"pdf-reader","command":"npx","args":["@sylphx/pdf-reader-mcp"]}'

Cursor

1. 打开 设置 → MCP → 添加新 MCP 服务器
2. 选择 命令 类型
3. 输入：npx @sylphx/pdf-reader-mcp

Windsurf

将以下内容添加到你的 Windsurf MCP 配置中：

{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"]
    }
  }
}

Cline

将以下内容添加到 Cline 的 MCP 设置中：

{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"]
    }
  }
}

Warp

1. 进入 设置 → AI → 管理 MCP 服务器 → 添加
2. 命令：npx，参数：@sylphx/pdf-reader-mcp

Smithery（一键安装）

npx -y @smithery/cli install @sylphx/pdf-reader-mcp --client claude

手动安装

# 快速启动 - 无需安装
npx @sylphx/pdf-reader-mcp

# 或全局安装
npm install -g @sylphx/pdf-reader-mcp

🎯 快速入门

基本用法

{
  "sources": [{
    "path": "documents/report.pdf"
  }],
  "include_full_text": true,
  "include_metadata": true,
  "include_page_count": true
}

结果：

• ✅ 提取了完整文本内容
• ✅ 包含 PDF 元数据（作者、标题、日期等）
• ✅ 统计了总页数
• ✅ 保留了未修改部分的结构共享

提取指定页面

{
  "sources": [{
    "path": "documents/manual.pdf",
    "pages": "1-5,10,15-20"
  }],
  "include_full_text": true
}

绝对路径（v1.3.0+）

// Windows - 两种格式均可！
{
  "sources": [{
    "path": "C:\\Users\\John\\Documents\\report.pdf"
  }],
  "include_full_text": true
}

// Unix/Mac
{
  "sources": [{
    "path": "/home/user/documents/contract.pdf"
  }],
  "include_full_text": true
}

不再出现 "不允许使用绝对路径" 错误！

提取图像并保持自然顺序

{
  "sources": [{
    "path": "presentation.pdf",
    "pages": [1, 2, 3]
  }],
  "include_images": true,
  "include_full_text": true
}

响应包含：

• 文本和图像按文档原始顺序排列（按 Y 坐标排序）
• Base64 编码的图像及元数据（宽度、高度、格式）
• 保留自然阅读顺序，便于 AI 理解

批量处理

{
  "sources": [
    { "path": "C:\\Reports\\Q1.pdf", "pages": "1-10" },
    { "path": "/home/user/Q2.pdf", "pages": "1-10" },
    { "url": "https://example.com/Q3.pdf" }
  ],
  "include_full_text": true
}

⚡ 所有 PDF 将自动并行处理！

✨ 特性

核心功能

• ✅ 文本提取 - 整个文档或指定页面，支持智能解析
• ✅ 图像提取 - Base64 编码，附带完整元数据（宽度、高度、格式）
• ✅ 内容排序 - 基于 Y 坐标的布局保持，确保自然的阅读顺序
• ✅ 元数据提取 - 作者、标题、创建日期及自定义属性
• ✅ 页数统计 - 快速统计，无需加载全部内容
• ✅ 双源支持 - 本地文件（绝对路径或相对路径）和 HTTP/HTTPS URL
• ✅ 批量处理 - 可同时处理多个 PDF 文件

高级特性

• ⚡ 5-10倍性能提升 - 使用 Promise.all 并行处理页面
• 🎯 智能分页 - 支持提取范围，如“1-5,10-15,20”
• 🖼️ 多格式图像 - 自动检测 RGB、RGBA 和灰度图像
• 🛡️ 路径灵活性 - 支持 Windows、Unix 路径以及相对路径（v1.3.0）
• 🔍 错误容错性 - 每页独立错误处理，并提供详细错误信息
• 📏 大文件支持 - 高效流式处理与内存管理
• 📝 类型安全 - 完全 TypeScript 实现，启用严格模式

🆕 v1.3.0 新增内容

🎉 现已支持绝对路径！

// ✅ Windows
{ "path": "C:\\Users\\John\\Documents\\report.pdf" }
{ "path": "C:/Users/John/Documents/report.pdf" }

// ✅ Unix/Mac
{ "path": "/home/john/documents/report.pdf" }
{ "path": "/Users/john/Documents/report.pdf" }

// ✅ 相对路径（仍可使用）
{ "path": "documents/report.pdf" }

其他改进：

• 🐛 修复了 Zod 验证错误处理问题
• 📦 更新所有依赖至最新版本
• ✅ 103 项测试通过，覆盖率保持在 94% 以上

📖 API 参考

read_pdf 工具

一个工具即可完成所有 PDF 操作。

参数

源对象

{
  path?: string;        // 本地文件路径（绝对或相对）
  url?: string;         // PDF 的 HTTP/HTTPS URL
  pages?: string | number[];  // 要提取的页面：“1-5,10”或 [1,2,3]
}

示例

仅元数据（快速）：

{
  "sources": [{ "path": "large.pdf" }],
  "include_metadata": true,
  "include_page_count": true,
  "include_full_text": false
}

从 URL：

{
  "sources": [{
    "url": "https://arxiv.org/pdf/2301.00001.pdf"
  }],
  "include_full_text": true
}

指定页面范围：

{
  "sources": [{
    "path": "manual.pdf",
    "pages": "1-5,10-15,20"  // 提取第 1、2、3、4、5、10、11、12、13、14、15、20 页
  }]
}

🔧 高级用法

文档布局：
┌─────────────────────┐
│ [标题]       Y:100 │
│ [图片]       Y:150 │
│ [文本]       Y:400 │
│ [照片 A]     Y:500 │
│ [照片 B]     Y:550 │
└─────────────────────┘

响应顺序：
[
  { type: "text", text: "标题..." },
  { type: "image", data: "..." },
  { type: "text", text: "..." },
  { type: "image", data: "..." },
  { type: "image", data: "..." }
]

{
  "sources": [{ "path": "manual.pdf" }],
  "include_images": true
}

{
  "images": [{
    "page": 1,
    "index": 0,
    "width": 1920,
    "height": 1080,
    "format": "rgb",
    "data": "base64-encoded-png..."
  }]
}

{ "path": "C:\\Users\\John\\file.pdf" }
{ "path": "/home/user/file.pdf" }

{ "path": "docs/report.pdf" }
{ "path": "./2024/Q1.pdf" }

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"],
      "cwd": "/path/to/documents"
    }
  }
}

{ "sources": [{ "path": "big.pdf", "pages": "1-20" }] }

// 步骤 1：获取页数
{ "sources": [{ "path": "big.pdf" }], "include_full_text": false }

// 步骤 2：提取部分页面
{ "sources": [{ "path": "big.pdf", "pages": "50-75" }] }

{
  "sources": [
    { "path": "big.pdf", "pages": "1-50" },
    { "path": "big.pdf", "pages": "51-100" }
  ]
}

🔧 故障排除

“不允许使用绝对路径”

解决方案： 升级到 v1.3.0+

npm update @sylphx/pdf-reader-mcp

然后完全重启您的 MCP 客户端。

“文件未找到”

原因：

• 文件路径不存在
• 工作目录设置错误
• 权限不足

解决方案：

使用绝对路径：

{ "path": "C:\\Full\\Path\\file.pdf" }

或者配置 cwd：

{
  "pdf-reader-mcp": {
    "command": "npx",
    "args": ["@sylphx/pdf-reader-mcp"],
    "cwd": "/path/to/docs"
  }
}

“未显示任何工具”

解决方案：

npm cache clean --force
rm -rf node_modules package-lock.json
npm install @sylphx/pdf-reader-mcp@latest

然后完全重启 MCP 客户端。

🌐 HTTP 传输（远程访问）

默认情况下，PDF Reader MCP 使用 stdio 传输进行本地使用。您也可以将其作为 HTTP 服务器运行，以便从多台机器进行远程访问。

快速入门

# 以 HTTP 服务器模式运行，监听 8080 端口
MCP_TRANSPORT=http npx @sylphx/pdf-reader-mcp

环境变量

Docker 部署

FROM oven/bun:1
WORKDIR /app
RUN bun add @sylphx/pdf-reader-mcp
ENV MCP_TRANSPORT=http
ENV MCP_HTTP_PORT=8080
EXPOSE 8080
CMD ["bun", "node_modules/@sylphx/pdf-reader-mcp/dist/index.js"]

MCP 客户端配置（HTTP）

{
  "servers": {
    "pdf-reader": {
      "type": "http",
      "url": "https://your-server.com/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

端点

🏗️ 架构

技术栈

设计原则

• 🔒 安全第一 - 灵活路径，安全默认
• 🎯 简单接口 - 一个工具，所有操作
• ⚡ 性能 - 并行处理，高效内存
• 🛡️ 可靠性 - 每页隔离，详细错误
• 🧪 质量 - 94%+ 覆盖率，严格 TypeScript
• 📝 类型安全 - 无 any 类型，严格模式
• 🔄 向后兼容 - 始终平滑升级

🧪 开发

git clone https://github.com/SylphxAI/pdf-reader-mcp.git
cd pdf-reader-mcp
pnpm install && pnpm build

pnpm run build       # 编译 TypeScript
pnpm run test        # 运行 103 个测试
pnpm run test:cov    # 覆盖率（94%+）
pnpm run check       # 代码检查 + 格式化
pnpm run check:fix   # 自动修复
pnpm run benchmark   # 性能测试

feat(images): 添加 WebP 支持
fix(paths): 处理 UNC 路径
docs(readme): 更新示例

📚 文档

• 📖 完整文档 - 全面指南
• 🚀 入门指南 - 快速开始
• 📘 API 参考 - 详细 API
• 🏗️ 设计文档 - 架构说明
• ⚡ 性能文档 - 基准测试
• 🔍 对比文档 - 与替代方案比较

🗺️ 路线图

✅ 已完成

• 图像提取（v1.1.0）
• 并行加速 5-10 倍（v1.1.0）
• Y 坐标排序（v1.2.0）
• 绝对路径支持（v1.3.0）
• 测试覆盖率 94%+（v1.3.0）

🚀 下一步

• 扫描 PDF 的 OCR
• 注释提取
• 表单字段提取
• 表格检测
• 100+ MB 流式处理
• 高级缓存
• PDF 生成

欢迎在 讨论区 投票！

🏆 认可

被以下平台收录：

• Smithery - MCP 目录
• Glama - AI 市场
• MseeP.ai - 安全认证

全球信赖 • 企业采用 • 实战检验

🤝 支持

• 🐛 Bug Reports
• 💬 Discussions
• 📖 Documentation
• 📧 Email

请支持我们： ⭐ 星标 • 👀 关注 • 🐛 报告 bug • 💡 提供建议 • 🔀 贡献

📊 统计

103 个测试 • 94%+ 覆盖率 • 生产就绪

📄 许可证

MIT © Sylphx

🙏 致谢

基于以下技术构建：

• PDF.js - Mozilla PDF 引擎
• Bun - 高效 JavaScript 运行时

特别感谢开源社区 ❤️

由 Sylphx 提供支持

本项目使用了以下 @sylphx 包：

• @sylphx/mcp-server-sdk - MCP 服务器框架
• @sylphx/vex - 模式验证
• @sylphx/biome-config - Biome 配置
• @sylphx/tsconfig - TypeScript 配置
• @sylphx/bump - 版本管理
• @sylphx/doctor - 项目健康检查

星标历史

pdf-reader-mcp 快速上手指南

pdf-reader-mcp 是一个生产级的 Model Context Protocol (MCP) 服务器，专为 AI Agent 设计，提供企业级的 PDF 处理能力。它支持并行处理（速度提升 5-10 倍）、基于 Y 轴坐标的自然内容排序以及高容错率的页面提取。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 建议安装 LTS 版本（v18 或更高），因为该工具通过 npx 运行。
• AI 客户端: 已安装支持 MCP 协议的客户端（如 Claude Desktop, Cursor, Windsurf, Cline, VS Code 等）。
• 网络环境: 能够访问 npm registry 以拉取包。
  • 国内加速建议: 如果下载缓慢，可配置淘宝镜像源：

  npm config set registry https://registry.npmmirror.com
  

安装步骤

根据您的使用场景，选择以下任一方式进行配置：

方式一：命令行快速添加 (推荐 Claude Code 用户)

如果您使用的是 Claude Code，可以直接运行：

claude mcp add pdf-reader -- npx @sylphx/pdf-reader-mcp

方式二：配置文件手动添加 (Claude Desktop / Windsurf / Cline)

找到对应系统的配置文件 claude_desktop_config.json (或 MCP 配置文件)，添加以下配置：

配置文件路径参考：

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

配置内容：

{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"]
    }
  }
}

方式三：Cursor 编辑器

1. 打开 Settings → MCP → Add new MCP Server。
2. 类型选择 Command。
3. 输入命令：npx @sylphx/pdf-reader-mcp。

方式四：VS Code

在终端运行以下命令直接添加：

code --add-mcp '{"name":"pdf-reader","command":"npx","args":["@sylphx/pdf-reader-mcp"]}'

基本使用

配置完成后，重启您的 AI 客户端。您可以在对话中直接请求 AI 读取 PDF 文件，或者通过结构化参数调用 read_pdf 工具。

最简单的使用示例

直接向 AI 发送自然语言指令，例如：

"请读取当前目录下的 report.pdf 文件并总结主要内容。"

AI 将自动调用 MCP 工具，返回包含全文、元数据和页码的结构化信息。

高级用法示例 (结构化参数)

如果您需要更精细的控制（如提取特定页面、图片或元数据），可以使用以下 JSON 格式的参数：

1. 提取全文与元数据

{
  "sources": [{
    "path": "documents/report.pdf"
  }],
  "include_full_text": true,
  "include_metadata": true,
  "include_page_count": true
}

2. 提取指定页面范围 支持灵活的页码格式（如 "1-5,10,15-20"）：

{
  "sources": [{
    "path": "documents/manual.pdf",
    "pages": "1-5,10"
  }],
  "include_full_text": true
}

3. 支持绝对路径与远程 URL (v1.3.0+) 不再受限于相对路径，支持 Windows/Unix 绝对路径及 HTTP 链接：

{
  "sources": [
    { "path": "C:\\Users\\John\\Documents\\contract.pdf" }, 
    { "url": "https://arxiv.org/pdf/2301.00001.pdf" }
  ],
  "include_full_text": true
}

4. 提取图片并保持自然阅读顺序 开启 include_images 后，工具会按 Y 轴坐标排序返回文本和图片，保持文档原始布局逻辑：

{
  "sources": [{ "path": "presentation.pdf" }],
  "include_images": true,
  "include_full_text": true
}

核心特性提示

• 并行处理: 多页或多文件处理时自动并行，大幅提升速度。
• 智能排序: 基于 Y 坐标的内容排序，确保 AI 理解正确的阅读流（标题->图片->正文）。
• 容错性: 单个页面解析失败不会影响整个文档的处理。