PDF 阅读器 MCP 服务器 (@sylphlab/pdf-reader-mcp)

使您的 AI 代理（如 Cline）能够使用单一、灵活的工具安全地从项目环境中的 PDF 文件中读取和提取信息（文本、元数据、页数）。

安装

使用 npm（推荐）

在您的 MCP 主机环境或项目中作为依赖项安装：

pnpm add @sylphlab/pdf-reader-mcp # Or npm install / yarn add

配置你的 MCP 主机（例如mcp_settings.json ）以使用npx ：

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "npx",
      "args": ["@sylphlab/pdf-reader-mcp"],
      "name": "PDF Reader (npx)"
    }
  }
}

（确保主机为目标项目设置正确的cwd ）

使用 Docker

拉取镜像：

docker pull sylphlab/pdf-reader-mcp:latest

配置您的 MCP 主机来运行容器，并将您的项目目录挂载到/app ：

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project:/app", // Or use "$PWD:/app", "%CD%:/app", etc.
        "sylphlab/pdf-reader-mcp:latest"
      ],
      "name": "PDF Reader (Docker)"
    }
  }
}

本地构建（用于开发）

克隆： git clone https://github.com/sylphlab/pdf-reader-mcp.git
安装： cd pdf-reader-mcp && pnpm install
构建： pnpm run build
配置 MCP 主机：
{ "mcpServers": { "pdf-reader-mcp": { "command": "node", "args": ["/path/to/cloned/repo/pdf-reader-mcp/build/index.js"], "name": "PDF Reader (Local Build)" } } }
（确保主机为目标项目设置正确的cwd ）

快速入门

假设服务器正在运行并已在 MCP 主机中配置：

MCP 请求（从本地 PDF 获取元数据和第二页文本）：

{
  "tool_name": "read_pdf",
  "arguments": {
    "sources": [
      {
        "path": "./documents/my_report.pdf",
        "pages": [2]
      }
    ],
    "include_metadata": true,
    "include_page_count": false, // Default is true, explicitly false here
    "include_full_text": false // Ignored because 'pages' is specified
  }
}

预期响应片段：

{
  "results": [
    {
      "source": "./documents/my_report.pdf",
      "success": true,
      "data": {
        "page_texts": [
          { "page": 2, "text": "Text content from page 2..." }
        ],
        "info": { ... },
        "metadata": { ... }
        // num_pages not included as requested
      }
    }
  ]
}

为什么选择这个项目？

**🛡️ 安全：**将文件访问严格限制在项目根目录中。
**🌐 灵活：**同时处理本地相对路径和公共 URL。
**🧩 合并：**单个read_pdf工具可满足多种提取需求（全文、特定页面、元数据、页数）。
**⚙️ 结构化输出：**以可预测的 JSON 格式返回数据，便于代理解析。
**🚀 轻松集成：**设计用于通过npx或 Docker 在 MCP 环境中无缝使用。
**✅ 强大：**使用pdfjs-dist进行可靠解析，使用 Zod 进行输入验证。

性能优势

使用 Vitest 对示例 PDF 进行的初始基准测试表明其能够有效处理各种操作：

设想	每秒操作数 (hz)	相对速度
处理不存在的文件	~12,933	最快的
获取全文	~5,575
获取特定页面（第 1 页）	~5,329
获取特定页面（第 1 页和第 2 页）	~5,242
获取元数据和页数	~4,912	最慢

（hz 越高表示性能越好。结果可能因 PDF 复杂性和环境而异。）

有关更多详细信息和未来计划，请参阅性能文档。

特征

从 PDF 文件中读取全文内容。
读取特定页面或页面范围的文本内容。
读取 PDF 元数据（作者、标题、创建日期等）。
获取 PDF 的总页数。
在单个请求中处理多个 PDF 源（本地路径或 URL）。
在定义的项目根目录内安全地运行。
通过 MCP 提供结构化 JSON 输出。
可通过 npm 和 Docker Hub 获得。

设计理念

该服务器优先考虑通过上下文限制实现的安全性、通过结构化数据传输实现的效率以及易于集成到AI代理工作流的简单性。它致力于最小化依赖项，并依赖于强大的pdfjs-dist库。

查看完整的设计理念文档。

与其他解决方案的比较

与直接文件访问（通常不可行）或通用文件系统工具相比，此服务器提供特定于 PDF 的解析功能。与外部 CLI 工具（例如pdftotext ）不同，它提供安全、集成的 MCP 接口和结构化输出，从而增强了 AI 代理的可靠性和易用性。

请参阅完整的比较文档。

未来计划（路线图）

文档：
- 完成所有文档部分（指南、API、设计、比较）。
- 解决 TypeDoc 问题并生成 API 文档。
- 添加更多示例和高级使用模式。
- 为文档网站实施 PWA 支持和移动优化。
- 在文档网站添加分享按钮和增长指标。
基准测试：
- 使用不同的 PDF 文件（大小、复杂性）进行全面的基准测试。
- 测量内存使用情况。
- 比较 URL 与本地文件的性能。
核心功能：
- 探索针对非常大的 PDF 文件的潜在优化。
- 研究提取图像或注释的选项（长期）。
测试：
- 在切实可行的情况下将测试覆盖率提高至 100%。
- 一旦可行，添加运行时测试。

文档

有关详细使用方法、API 参考和指南，请访问**完整文档网站**（部署后链接将更新）。

社区与支持

**发现了 Bug 或有功能请求？**请在GitHub Issues上提交问题。
**想贡献力量吗？**我们欢迎您的贡献！请参阅CONTRIBUTING.md 。
**加星标并关注：**如果您发现此项目有用，请考虑加星标⭐并关注👀 GitHub上的存储库以表示您的支持并保持更新！

执照

该项目已获得MIT 许可。

PDF Reader MCP Server

Integrations