pdf-mcp
PyPI version
Python 3.11 to 3.14
License: MIT
GitHub Issues
CI
codecov
Downloads
하나의 MCP 도구로 PDF 문서 전체 또는 폴더 단위에서 에이전트 기반 RAG 구현.
에이전트가 언제 검색할지 결정하고, pdf-mcp는 검색(retrieval)을 수행하여 발췌된 내용만 반환합니다. 이는 MCP 서버로, Claude Code 및 기타 AI 에이전트가 의미나 키워드를 통해 하나의 PDF 또는 전체 폴더를 검색하고, 중요한 페이지만 읽어내며, 다단 구성이나 일본어 레이아웃에서도 테이블, 이미지, 스캔된 텍스트를 깔끔하게 추출할 수 있게 해줍니다. 대규모 코퍼스(corpora) 워밍을 위해 선택적으로 CUDA 가속이 지원됩니다.
mcp-name: io.github.jztan/pdf-mcp
브라우저에서 사용해 보기
AI 에이전트가 무엇을 보는지 확인하기 →
PDF 파일 하나 또는 전체 폴더를 드롭하고, 에이전트가 코퍼스를 분류(triage)하고 모든 문서를 한 번에 검색하며, 토큰의 극히 일부만을 사용하여 필요한 페이지만 읽는 것을 확인해 보세요. 100% 클라이언트 측에서 작동하며 설치가 필요 없습니다.
<p align="center">
<a href="https://pdf-mcp.jztan.com/"><img src="https://raw.githubusercontent.com/jztan/pdf-mcp/develop/docs/images/demo.gif" alt="pdf-mcp 브라우저 데모: AI 에이전트가 6개 PDF 코퍼스를 워밍하고, 이를 분류하며, 6개 문서 전체를 검색한 후, 코퍼스의 97.3%가 컨텍스트 창에 진입하지 않은 상태에서 일치하는 페이지만 읽는 모습" width="760"></a>
</p>
pdf-mcp를 사용해야 하는 이유?
| pdf-mcp 없이 | pdf-mcp 사용 시 |
|---|
| 대용량 PDF | 컨텍스트 오버플로우(Context overflow) | 필요한 페이지만 읽기 |
| ... | | |
설치하기
Claude Desktop: 별도의 설치가 필요 없습니다
- pdf-mcp.mcpb 다운로드.
- Claude Desktop에서 **설정(Settings) > 확장 기능(Extensions)**으로 이동하여 해당 파일을 페이지에 끌어다 놓고 **설치(Install)**를 클릭합니다.
- 위치별로 PDF에 대해 질문하거나, 예를 들어 "pdf-mcp를 사용하여 C:\Users\me\Downloads\report.pdf 요약해 줘"와 같이 요청하거나, 전체 폴더에 대해 질문할 수 있습니다.
최초 시작 시 pdf-mcp의 구성 요소(약 250 MB)가 다운로드되며 몇 분 정도 걸릴 수 있고, 이후 시작은 몇 초 만에 완료됩니다. 스캔된 페이지의 OCR 기능이 포함되어 있으며, 첫 번째 스캔 페이지를 처리할 때 영어 전용 Tesseract(약 14 MB)가 다운로드됩니다.
Windows 10 이상 또는 macOS 13 이상 (Apple Silicon의 경우 14)이 필요하며, Claude Desktop의 채팅 환경에서 작동합니다. 업데이트, 제거 및 기타 세부 정보는 docs/clients.md를 참조하세요.
Claude Code 및 기타 MCP 클라이언트
Python 3.11부터 3.14까지 필요합니다. 3.15 버전에서는 종속성(dependency)에 아직 3.15 빌드가 없기 때문에 설치 프로그램이 매우 오래된 버전을 사용하게 됩니다. uv 또는 pipx를 사용하여 pdf-mcp 명령어를 설치하세요:
pip install pdf-mcp는 가상 환경(virtual environment) 내부에서 작동합니다. Homebrew의 Python과 최근 Debian 및 Ubuntu 버전은 시스템 전체에 pip을 설치하는 것을 거부합니다.
이후 클라이언트에 추가하세요. Claude Code의 경우:
claude mcp add pdf-mcp -- pdf-mcp
VS Code, Cursor, Codex CLI, Kiro 또는 기타 MCP 클라이언트의 경우 **docs/clients.md**를 참조하세요. 그런 다음 에이전트에게 PDF 읽기를 요청하면 됩니다.
검색(Search), 코퍼스 도구(corpus tools), 표(tables), 다중 열 및 CJK 읽기 순서가 별도의 설정 없이 바로 작동합니다. 비영어권 문서의 경우 언어 지원을 참조하세요. 스캔된 페이지의 OCR 기능 역시 Tesseract가 필요합니다:
brew install tesseract
sudo apt install tesseract-ocr
winget install -e --id UB-Mannheim.TesseractOCR
선택 사항: NVIDIA 카드에서 CUDA 임베딩을 사용하면 대용량 폴더를 한두 자릿수(orders of magnitude) 더 빠르게 처리할 수 있습니다. docs/configuration.md 참조.
Python으로 구현하기
pdf-mcp의 도구들은 일반적인 Python 함수이므로, 서버를 실행할 필요 없이 이를 임포트하여 Anthropic SDK에 PDF를 전달할 수 있습니다. 질문용과 전체 문서용으로 두 개의 실행 가능한 스크립트를 제공합니다: examples/.
이것이 존재하는 이유와 그 과정에서 해결된 문제들: Claude의 100페이지 PDF 제한과 이를 우회한 방법
단일 거대 도구 대신 13개의 전문화된 도구를 사용합니다. 일반적인 패턴은 다음과 같습니다: 계획을 위한 pdf_info, 위치 파악을 위한 pdf_search (그의 문단 발췌문이 질문에 대한 답을 직접적으로 제공하는 경우가 많음), 더 많은 정보가 필요할 때 사용하는 pdf_read_pages. 폴더의 경우, 분류를 위해 pdf_corpus_overview를 사용한 후 pdf_corpus_search를 사용합니다.
| 도구 | 기능 |
|---|
pdf_info | 페이지 수, 메타데이터, TOC 요약, 스캔된 페이지 감지. 가장 먼저 호출하세요. |
| ... | |
이 도구들 중 어떤 것으로 반환되는 텍스트는 PDF에서 추출된 신뢰할 수 없는(untrusted) 콘텐츠입니다. pdf_info(content_trust=True)는 인간 독자가 볼 수 없는 숨겨진 텍스트를 보고하며, 읽기 도구들은 페이지별로 이를 표시합니다.
예시 프롬프트:
"/path/to/document.pdf에 있는 PDF를 읽어줘"
"공급망 위험을 논하는 페이지는 어느 페이지야?"
"훈련 과정에 대한 섹션을 찾아줘"
...```
전체 참조 및 모든 매개변수와 응답 형태: **[docs/tool-reference.md](docs/tool-reference.md)**. 임베딩 모델 선택: **[docs/embedding-models.md](docs/embedding-models.md)**.
## 예시 워크플로우(Example Workflow)
대용량 문서(예: 200페이지 연례 보고서)의 경우:
사용자: "이 연례 보고서의 위험 요인을 요약해줘"
에이전트 워크플로우:
...```
원격/HTTP 전송(Remote / HTTP transport)
STDIO는 기본값이며 위의 모든 예시에서 사용됩니다. pdf-mcp-http는 프로세스를 생성할 수 없는 클라이언트(Anthropic API MCP 커넥터, claude.ai 사용자 지정 커넥터 등)와 여러 클라이언트가 공유하는 워밍업 코퍼스에 대해 동일한 도구를 HTTP를 통해 제공합니다.
export PDF_MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
pdf-mcp-http
경로는 서버에서 해결되므로, HTTP 에이전트는 이미 존재하는 것(허용 목록에 등록된 루트 아래의 파일 또는 서버가 가져오는 URL)을 읽습니다. 자체 장치에서 파일을 전달할 수는 없습니다. 이는 단일 테넌트(single-tenant)이며 폐쇄 실패(fails closed) 방식을 따릅니다. 즉, 인증 토큰도 없고 [paths] 허용 목록도 없으면, 열린 엔드포인트를 제공하기보다는 프로세스가 종료됩니다.
Docker 이미지는 모든 것이 포함되어 있어 첫 요청부터 모든 도구가 작동하도록 amd64 및 arm64용으로 GHCR에 게시됩니다:
./deploy.sh
cp your.pdf documents/
배포하기 전에 신뢰 경계(trust boundary) 및 위협 모델(threat model)에 대해서는 **docs/remote-access.md**를 읽고, 설정(setup), 클라이언트 구성(client config), 토큰 순환(token rotation)에 대해서는 **docs/configuration.md**를 참고하십시오.
Configuration (설정)
pdf-mcp는 별도의 설정 없이 작동합니다(out of the box). 서버가 접근할 수 있는 경로 및 URL 호스트를 제한하거나, 캐시 및 워커 설정을 조정하거나, 자체 콘텐츠 신뢰 구문(content-trust phrases)을 추가하려면 **docs/configuration.md**를 참조하십시오.
Roadmap (로드맵)
계획된 기능 및 릴리스 기록은 ROADMAP.md를 참조하십시오.
Contributing (기여)
기여는 환영합니다. 설정, 검사(checks), 일관성 평가 하네스(coherence eval harness), 그리고 품질 루프 가이드라인(quality-loop guidelines)에 대해서는 **docs/contributing.md**를 참조하십시오.
Contributors (기여자)
코드, 검토(reviews), 테스트, 기능 요청을 통해 이 프로젝트 개선에 도움을 준 모든 분들께 감사드립니다.
<!-- contributors:start -->
@Summer907 · @ebbsanchez · @VooDisss · @DerDennisOP · @deepdmk · @TheSOV · @janLo · @bbulkow · @HillsCloud · @phinnphace
<!-- contributors:end -->
<a href="https://github.com/jztan/pdf-mcp/graphs/contributors">
<img src="https://contrib.rocks/image?repo=jztan/pdf-mcp" alt="기여자(Contributors)" />
</a>
릴리스별 기여자는 Changelog에 나열되어 있습니다.
보안 (Security)
취약점을 발견하셨나요? 위협 모델(threat model), 보고 채널(reporting channel), 예상 응답 시간표(expected response timeline)는 SECURITY.md를 참조하십시오. 패치되지 않은 보안 보고에 대해서는 공개 GitHub 이슈를 열지 마십시오.
라이선스 (License)
MIT. LICENSE를 참조하십시오.
링크 (Links)
블로그 게시물 (Blog posts)
pdf-mcp 구축 과정에서의 배경, 벤치마크 및 설계 노트:
시작하기(Getting started)
[100페이지가 넘는 PDF를 Claude API로 전송하는 방법 (How to Send PDFs Over 100 Pages to Claude's API)]:
Claude API의 실제 페이지 및 토큰 제한 측정, 그리고 이를 우회하는 두 가지 방법: 질문을 위해 디스크에서 PDF 검색하기, 전체 문서 작업을 위해 텍스트 창(window) 처리 및 이미지 페이지만 렌더링하기
[AI 에이전트가 실제로 PDF를 읽는 방법 (How Claude Code Actually Reads PDFs)]:
AI 에이전트가 pdf-mcp 도구를 사용하여 PDF 문서를 읽고 탐색하는 방식
[AI 에이전트가 PDF를 읽어야 하는 방법: 프로덕션 환경에서 살아남은 5가지 패턴 (How AI Agents Should Read PDFs: 5 Patterns That Survived Production)]:
대규모로 PDF를 탐색해야 하는 에이전트를 위한 다섯 가지 실무 검증 패턴
코퍼스 및 다중 문서 검색 (Corpus & Multi-Document Search)
- 지식 기반은 단지 폴더일 뿐: 코퍼스 도구(corpus tools)를 사용하여 PDF 파일 폴더를 에이전트 지식 기반으로 변환하며, 데이터 수집 파이프라인(ingestion pipeline)이나 벡터 스토어(vector store)가 필요 없습니다.
- 벡터 데이터베이스 없이 AI 에이전트를 위한 문서 간 검색: 왜 BM25 점수는 문서별 인덱스(per-document indexes)에 걸쳐 병합되지 않고 순위(ranks)만 병합되는지, 그리고 2단계 RRF가 100개 PDF 코퍼스에서 184개의 채점된 쿼리 중 84.8%의 경우 골드 문서(gold document)를 상위 3위에 배치하는 방법.
- Amazon Bedrock이 나의 RAG 개선에 어떻게 도움이 되었는지: 동등한 2,000 토큰 예산으로 pdf_corpus_search를 Bedrock Knowledge Bases와 벤치마킹한 결과, 4센트 비용으로 8개월간의 자체 테스트에서 놓쳤던 두 가지 버그가 발견되었습니다: 이미 검색했던 페이지의 답변을 폐기하는 발췌본 선택기(excerpt picker)와 짧은 답변을 숨기는 페이지당 하나의 임베딩(embedding).
- AI 에이전트에게 PDF 검색 도구는 여전히 중요할까요?: 120개 논문에 걸친 53개의 다중 논문 질문에 대해 pdf-mcp 유무와 관계없이 Claude Code를 테스트한 결과: 답변 품질은 동일했지만, 검색 도구는 질문당 187페이지 대신 7.5페이지를 읽었고 92초 대신 25초 만에 답변했습니다.
검색 및 검색(Search & retrieval)
