PDF 리더 MCP 서버 (@sylphlab/pdf-reader-mcp)

프로젝트 컨텍스트 내에서 단일하고 유연한 도구를 사용하여 AI 에이전트(클라인 등)에게 PDF 파일에서 정보(텍스트, 메타데이터, 페이지 수)를 안전하게 읽고 추출하는 기능을 제공하세요.

설치

npm 사용(권장)

MCP 호스트 환경이나 프로젝트에 종속성으로 설치하세요.

지엑스피1

npx 사용하도록 MCP 호스트(예: mcp_settings.json )를 구성합니다.

{
  "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에서 메타데이터와 2페이지 텍스트 가져오기):

{
  "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를 사용합니다.

성능 이점

샘플 PDF에서 Vitest를 사용한 초기 벤치마크는 다양한 작업을 효율적으로 처리하는 모습을 보여줍니다.

대본	초당 작업(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 참조 및 가이드를 보려면 전체 문서 웹사이트를 방문하세요(링크는 배포 시 업데이트됨).

커뮤니티 및 지원

버그를 발견하셨거나 기능 요청이 있으신가요? GitHub Issues 에 이슈를 남겨주세요.
기여하고 싶으신가요? 기여를 환영합니다! CONTRIBUTING.md를 참조하세요.
별표 표시 및 시청: 이 프로젝트가 유용하다고 생각되시면 GitHub 저장소에 별표 표시 ⭐와 👀을 눌러서 여러분의 지지를 표시하고 최신 소식을 받아보세요!

특허

이 프로젝트는 MIT 라이선스 에 따라 라이선스가 부여되었습니다.

PDF Reader MCP Server

Integrations