使用说明

PDF MCP服务器

韩语 | 英语

将PDF解析工具打包到模型上下文协议（MCP）服务器，与Cursor IDE集成的实用项目。

体系结构概述

PDF MCP服务器通过MCP协议充当Cursor IDE和PDF文件之间的桥梁。

为什么制作了呢？

Cursor IDE中的AI默认无法读取PDF文件。每当我想分析文档、论文和PDF资料时，我都很郁闷。这个MCP服务器可以解决这个问题。

现实的告白：不是创新。只是把现有的PDF解析库用MCP界面包起来而已。但有时最实用的解决方案也是最无聊的解决方案。

当前状态

🔧完成的东西：

基于McpServer API的MCP服务器结构
使用pdf-parse库提取PDF文本
提取PDF元数据
PDF文件验证功能
按页面提取文本（范围，选择特定页面）
完整的测试套件（通过8/8测试）
TypeScript构建系统
基于Docker的开发环境
完成Cursor IDE集成并验证实际操作

🔧 下一步：

提取表格数据
提取图像
GitHub Actions CI/CD设置

功能

当前实施的功能

extract_pdf_text：从PDF文件中提取全文（大小限制：100KB）
extract_pdf_pages：提取PDF特定页面或页面范围文本（大小限制：200KB）
get_pdf_元数据：提取PDF元数据（标题、作者、创建日期等+文本预览200个字符）
validate_pdf：验证PDF文件格式和大小限制

技术堆栈

TypeScript -即使是Rapper项目，类型稳定性也很重要。
pdf解析 -经验证的PDF解析库
@模型上下文协议/sdk v1.15.1-最新MCP SDK
动物圈 -验证MCP工具模式
开玩笑 -测试框架
码头工人 -跨平台开发环境

设置

基本要求

Docker桌面（启用WSL集成）
光标IDE

设置开发环境

存储库克隆：

git clone https://github.com/EEager/pdf-mcp-server.git
cd pdf-mcp-server

依赖性安装：

docker run -it --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 npm install

项目构建：

docker run --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 npx tsc

测试项目（可选）：

# 실행해보고 docker ps -a에서 잘 돌아가는지 확인하세요
docker run -it --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 node dist/index.js

设置Cursor IDE

[光标设置]-[工具和集成]-[添加自定义MCP] 可以通过修改mcp.json配置文件。

重要信息：设置文件访问权限

PDF MCP服务器通过安装Docker卷来访问文件。 只能读取挂载目录中的文件。

Cursor MCP设置文件（~/.cursor/mcp.json 或者 ~/.config/cursor/mcp.json）：（配置文件可能会根据cursor update情况而更改）

{
  "mcpServers": {
    "pdf-parser": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        // !본인의 pdf-mcp-server 설치 경로로 수정하세요. 아래의 경우 wsl환경의 workspace 경로입니다.
        "-v", "\\\\wsl$\\Ubuntu\\home\\eager\\workspace\\pdf-mcp-server:/app", 

        // !PDF 파일들이 저장된 폴더 경로로 수정하세요. 아래의 경우 cursor_mcp_dir 폴더 밑에 pdf 파일들이 존재합니다. 
        "-v", "D:\\cursor_mcp_dir:/workspace",
        "-w", "/app",
        "node:20",
        "node",
        "dist/index.js"
      ]
    }
  }
}

设置说明：

\\\\wsl$\\Ubuntu\\home\\eager\\workspace\\pdf-mcp-server:/app：安装MCP服务器代码
D:\\cursor_mcp_dir:/workspace: 安装PDF文件所在的目录（必需！）
PDF文件 /workspace/ 只能通过路径访问

重要: D:\\cursor_mcp_dir将更改为包含实际PDF文件的Windows目录。

验证正在运行的MCP服务器

Cursor IDE自动运行Docker容器：

# 실행 중인 컨테이너 확인
docker ps

# 예시 출력:
# CONTAINER ID   IMAGE     COMMAND                  CREATED       STATUS       NAMES
# abc123def456   node:20   "node dist/index.js"     2 minutes ago Up 2 minutes suspicious_turing

✅如果在cursor IDE中正常注册了mcp

保存mcp.json后，可以立即确认已注册mcp。

使用方法

设置完成后，Cursor IDE可以：

1.提取PDF全文（extract_pdf_text）

사용자: "/workspace/document.pdf 파일의 내용을 읽어줄 수 있어?"

응답: PDF 파일에서 추출된 전체 텍스트(최대 100KB)와 페이지 수, 기본 메타데이터가 함께 제공됩니다.
큰 파일은 자동으로 잘림 처리됩니다.

2.按PDF页面提取文本（extract_pdf_pages）新功能

사용자: "/workspace/document.pdf 파일의 5-10페이지만 읽어줄 수 있어?"
또는: "/workspace/document.pdf 파일의 1, 3, 5페이지만 추출해줘"

응답: 지정된 페이지들의 텍스트(최대 200KB)가 페이지별로 구분되어 제공됩니다.

按页提取选项：

页面范围: startPage: 5, endPage: 10 （第5-10页）
特定页面: pageNumbers: [1, 3, 5, 7] （第1、3、5、7页）
从首页开始: startPage: 10 （第10页至最后）

3.检查PDF元数据（get_pdf_metadata）

사용자: "/workspace/document.pdf 파일의 메타데이터가 뭐야?"

응답: 제목, 작성자, 생성일, 수정일, 페이지 수와 텍스트 미리보기(200자)가 제공됩니다.

4.验证PDF文件（validate_pdf）

사용자: "/workspace/document.pdf 파일이 유효한 PDF인가?"

응답: 파일 형식, 크기 제한, 접근 가능성을 확인한 검증 결과가 제공됩니다.

MCP工具列表

服务器提供的MCP工具：

工具名说明输入参数输出 |--------|------|---------------|------| | extract_pdf_text |提取PDF全文| filePath: string |文本、页面指数、元数据| | extract_pdf_pages |提取特定页面文本| filePath, startPage?, endPage?, pageNumbers? |每页文本，提取的页面列表| | get_pdf_metadata |提取元数据| filePath: string |标题、作者、创建日期等| | validate_pdf |PDF검증 | filePath: string |是否有效，错误消息|

实际测试结果

示例：第962页深度学习教材分析

1.validate_pdf

输入：

{
  "filePath": "/workspace/01_study/ai_ml/pytorch_deep_learning_Intro.pdf"
}

结果：

{
  "isValid": true,
  "filePath": "/workspace/01_study/ai_ml/pytorch_deep_learning_Intro.pdf",
  "message": "PDF file is valid"
}

2.获取_pdf_metadata

输入：

{
  "filePath": "/workspace/01_study/ai_ml/pytorch_deep_learning_Intro.pdf"
}

结果：

{
  "text": "Contents\n문서정보1\n00. 입문자들을위한조언(Q&A)2\n00.교육문의8\n00.\n유료\nE‑book\n안내\n9\n00.책과저자소개하기10\n01. [기초] ‑딥러닝을시작하기전에11\n01‑01코랩(Colab)과아나콘다12\n1.아나콘다(Anaconda)설치...",
  "pageCount": 962,
  "title": "딥 러닝 파이토치 교과서 - 입문부터 파인튜닝까지",
  "author": "이 책은 ...님이 구매하신 전자책입니다.",
  "creator": "WikiDocs",
  "producer": "xdvipdfmx (20210609)",
  "creationDate": "D:20250521134136+09'00'"
}

3.提取_pdf_text

输入：

{
  "filePath": "/workspace/01_study/ai_ml/pytorch_deep_learning_Intro.pdf"
}

结果：

{
  "text": "Contents\n문서정보1\n00. 입문자들을위한조언(Q&A)2...[100KB 제한으로 잘림]",
  "pageCount": 962,
  "metadata": { "title": "딥 러닝 파이토치 교과서...", "author": "..." },
  "truncated": true,
  "originalLength": 868068
}

4.extract_pdf_pages（新功能！）

输入-阅读特定章节：

{
  "filePath": "/workspace/01_study/ai_ml/pytorch_deep_learning_Intro.pdf",
  "startPage": 50,
  "endPage": 60
}

输入-仅限特定页面：

{
  "filePath": "/workspace/01_study/ai_ml/pytorch_deep_learning_Intro.pdf",
  "pageNumbers": [1, 5, 10, 100]
}

结果：

{
  "text": "--- 페이지 50 ---\n파이토치 기초 설명...\n\n--- 페이지 51 ---\n텐서 연산에 대한 내용...\n\n--- 페이지 52 ---\n...",
  "pageCount": 962,
  "extractedPages": [50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60],
  "metadata": { "title": "딥 러닝 파이토치 교과서...", "author": "..." },
  "truncated": false,
  "originalLength": 15420
}

在Cursor IDE中聊天时使用MCP工具的结果

开发

项目结构

pdf-mcp-server/
├── src/
│   ├── index.ts          # MCP 서버 진입점
│   ├── pdf-parser.ts     # PDF 파싱 로직
│   └── types.ts          # TypeScript 타입 정의
├── tests/
│   └── pdf-parser.test.ts # Jest 테스트 스위트
├── docs/
│   └── images/           # 문서 이미지
├── dist/                 # 빌드 결과물
├── package.json
├── tsconfig.json
└── README.md

开发脚本

# 빌드 (필수)
docker run --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 npx tsc

# 테스트
docker run -it --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 npm test

# 서버 실행 테스트 (선택사항 - Cursor가 자동으로 실행함)
docker run -it --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 node dist/index.js

请参见：Cursor IDE自动将MCP服务器作为Docker容器运行，开发时只需构建即可。

调试和日志检查

检查Docker容器日志

# 실행 중인 컨테이너 확인
docker ps

# 컨테이너 로그 확인 (컨테이너 이름으로)
docker logs <CONTAINER_NAME>

# 실시간 로그 확인
docker logs -f <CONTAINER_NAME>

示例日志输出

{"result":{"content":[{"type":"text","text":"{\n  \"isValid\": true,\n  \"filePath\": \"/workspace/01_study/ai_ml/pytorch_deep_learning_Intro.pdf\",\n  \"message\": \"PDF file is valid\"\n}"}]},"jsonrpc":"2.0","id":16}

使用MCP Inspector进行测试

# MCP 서버 기능 테스트
cd ~/workspace/pdf-mcp-server
npx @modelcontextprotocol/inspector node dist/index.js

实现说明

已解决的环境问题

WSL/Windows路径冲突：通过Docker容器化解决
npm权限问题：通过隔离Docker防止文件系统崩溃
MCP SDK版本不匹配：从不存在的0.2.0更新到最新的1.15.1
API更改：从旧服务器迁移到新的McpServer API
处理大量文本：限制文本大小以防止Cursor IDE崩溃
日期类型错误：通过安全的日期转换函数解决

体系结构决策

模块化设计：分离PDF解析逻辑和MCP服务器逻辑
全面测试：完全的测试覆盖范围，具有锁定的依赖性
类型安全性：使用zod验证设置严格的TypeScript
错误处理：优雅地处理文件操作和PDF解析错误
性能优化：通过限制文本大小确保客户端稳定性
分页处理：使用pdf-parse的pagerender回调提取页面文本

问题解决

常见问题

无法读取PDF文件：

检查Docker卷安装设置： "D:\\your_pdf_dir:/workspace"
文件路径为 /workspace/ 验证是否以开头
检查是否启用了Docker桌面WSL集成

MCP服务器连接失败：

检查Docker桌面是否在运行
验证Cursor MCP设置文件路径是否正确
重新启动Cursor IDE

构建错误：

在WSL中构建： docker run --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 npx tsc
重新安装依赖性： docker run -it --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 npm install

限制

文件访问：只能访问安装了Docker卷的目录中的文件
文件大小：大PDF（100 MB以上）因性能原因被拒绝
文本大小：全文限制为100KB，分页文本限制为200KB（Cursor IDE稳定性）
元数据：文本预览限制为200个字符
复杂的布局：表格或多级布局可能无法完全解析
扫描的PDF：OCR支持正在计划中，但尚未实施

许可证

MIT许可-因为共享是关怀，而且反正只是说唱歌手。

感谢的话

pdf解析 -负责实际PDF解析的繁重工作
MCP协议 -让这种联动成为可能的
光标IDE -为您创建值得扩展的IDE
Docker社区-解决环境兼容性噩梦

使用说明

PDF MCP服务器

体系结构概述

为什么制作了呢？

当前状态

功能

当前实施的功能

技术堆栈

设置

基本要求

设置开发环境

设置Cursor IDE

重要信息：设置文件访问权限

验证正在运行的MCP服务器

✅如果在cursor IDE中正常注册了mcp

使用方法

1.提取PDF全文（extract_pdf_text）

2.按PDF页面提取文本（extract_pdf_pages）新功能

3.检查PDF元数据（get_pdf_metadata）

4.验证PDF文件（validate_pdf）

MCP工具列表

实际测试结果

示例：第962页深度学习教材分析

1.validate_pdf

2.获取_pdf_metadata

3.提取_pdf_text

4.extract_pdf_pages（新功能！）

在Cursor IDE中聊天时使用MCP工具的结果

开发

项目结构

开发脚本

调试和日志检查

检查Docker容器日志

示例日志输出

使用MCP Inspector进行测试

实现说明

已解决的环境问题

体系结构决策

问题解决

常见问题

限制

许可证

感谢的话

相关 MCP

多格式文档转Markdown转换器

MCP代理服务器

PDF处理工具集

PDF文本提取服务

文件转 Markdown 转换器

嵌入数据库服务器