使用说明
PDF MCP服务器
Node.js服务器实现了用于PDF文本提取操作的模型上下文协议（MCP）。专为Claude Desktop与安全目录访问控制集成而构建。
基于以下模式 @模型上下文协议/服务器文件系统.
特性
- 单一工具:
extract_pdf_text-从PDF文件中提取纯文本 - 目录访问：与文件系统MCP服务器相同的安全模型
- 文本限制:
max_chars用于控制输出大小和令牌使用的参数 - 安全：路径验证和沙盒目录访问
- 快速：使用unpdf实现轻量级Node.js
安装
通用MCP客户端
将以下内容添加到您的mcp服务器配置文件中：
{
"mcpServers": {
"pdf-reader": {
"command": "npx",
"args": ["-y", "@johangorter/mcp-pdf-server", "/Users/username/Desktop"]
}
}
}
Claude Desktop的桌面扩展（.mcpb）
有关桌面扩展的更多信息，请参阅 MCPB官方文件.
- 下载
.mcpb文件来自 发布 页面。 - 导航到Claude Desktop中的“设置”>“扩展”
- 点击“安装扩展”并选择
.mcpb文件
用法
服务器提供了一个主要工具：
extract_pdf_text
使用可选的字符限制从PDF文件中提取文本内容。
参数：
path（字符串，必填）：允许目录中PDF文件的路径max_chars（数字，可选）：返回的最大字符数（默认值：无限制）
例子：
// Claude will call this tool when you ask:
// "Extract the first 1000 characters from report.pdf"
{
"tool": "extract_pdf_text",
"arguments": {
"path": "reports/quarterly-report.pdf",
"max_chars": 1000
}
}
配置
目录访问
将允许的目录指定为命令行参数：
npx @johangorter/mcp-pdf-server /path/to/documents /path/to/pdfs
根协议支持
服务器支持通过MCP根协议进行动态目录更新，无需重新启动即可在运行时更改目录。
错误处理
标准MCP错误代码：
-32602：无效参数（找不到文件，路径无效）-32603：内部错误（PDF解析失败，文件损坏）
依赖项
{
"@modelcontextprotocol/sdk": "^1.17.0",
"pdf-parse": "^1.1.1",
"zod-to-json-schema": "^3.23.5"
}
发展
先决条件
- Node.js 22+
- TypeScript
设置
# Clone the repository
git clone https://github.com/johan-gorter/mcp-pdf-server.git
cd mcp-pdf-server
# Install dependencies
npm install
# Build the project
npm run build
持续集成
本项目使用GitHub Actions进行自动化测试和部署：
- CI管道：对每个推送和拉取请求运行
- Ubuntu和Windows上的测试
- 运行linting、格式检查和测试
- 释放管道：package.json版本更改时触发
- 使用MCPB捆绑包创建GitHub版本
- 构建并发布Docker镜像
开发脚本
# Build TypeScript to JavaScript
npm run build
# Build in watch mode (rebuilds on file changes)
npm run watch
# Run the server locally for development
npm run dev
# Start the compiled server
npm run start
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverage
# Lint the code
npm run lint
# Fix linting issues
npm run lint:fix
# Format code with Prettier
npm run format
# Check code formatting
npm run format:check
# Clean build artifacts
npm run clean
测试
该项目使用Jest进行测试，并支持TypeScript：
# Run all tests
npm test
# Run tests in watch mode during development
npm run test:watch
# Generate test coverage report
npm run test:coverage
测试文件位于 src/__tests__/ 并遵循模式 *.test.ts.
MCPB捆绑包创建
此项目支持创建MCPB（MCP Bundle）文件，以便于分发和安装：
# Build the MCPB bundle
npm run build:mcpb
MCPB捆绑包包括：
- 编译的TypeScript服务器(
dist/) - 运行时依赖关系(
node_modules/) - 捆绑清单(
manifest.json) - 文档和许可证文件
只需单击一下，MCPB捆绑包就可以安装在Claude Desktop和其他MCP兼容客户端中。
Docker开发
使用Docker构建和运行：
# Build Docker image
docker build -t mcp-pdf-server .
# Run with Docker
docker run -i --rm \
--mount type=bind,src=/path/to/pdfs,dst=/pdfs \
mcp-pdf-server /pdfs
或者使用预构建的Docker镜像：
# Pull from GitHub Container Registry
docker pull ghcr.io/johan-gorter/mcp-pdf-server:latest
# Run the container
docker run -i --rm \
--mount type=bind,src=/path/to/pdfs,dst=/pdfs \
ghcr.io/johan-gorter/mcp-pdf-server:latest /pdfs
代码质量
该项目通过以下方式提高代码质量：
- TypeScript：强大的打字和编译时错误检查
- 埃斯林特：使用TypeScript特定规则进行代码linting
- 更漂亮：一致的代码格式
- 开玩笑：综合单元测试
项目结构
mcp-pdf-server/
├── src/
│ ├── __tests__/ # Test files
│ │ ├── lib.test.ts
│ │ ├── path-utils.test.ts
│ │ └── roots-utils.test.ts
│ ├── index.ts # Main server entry point
│ ├── lib.ts # Core functionality
│ ├── path-utils.ts # Path handling utilities
│ ├── path-validation.ts # Security validation
│ └── roots-utils.ts # MCP roots support
├── dist/ # Compiled JavaScript (generated)
├── coverage/ # Test coverage reports (generated)
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── jest.config.cjs # Jest testing configuration
├── .eslintrc.cjs # ESLint configuration
├── .prettierrc # Prettier configuration
├── Dockerfile # Docker build configuration
└── README.md
局限性
- 只有文本：无图像、表格或元数据提取
- 无OCR：没有嵌入文本的扫描PDF无法工作
- 记忆：大型PDF（>100MB）可能会导致内存问题
- 无并发处理：一次处理一个PDF
许可证
MIT许可证
