PDF Oxide MCP 서버 — AI 어시스턴트를 위한 PDF 추출

pdf-oxide-mcp는 AI 어시스턴트가 PDF 내용을 읽어 올 수 있게 해 주는 Model Context Protocol 서버입니다. 모든 처리는 로컬에서 수행되며, 파일이 컴퓨터를 벗어나지 않습니다.

crgx 설치 (한 번만)

crgx는 Rust 바이너리용 npx 스타일 실행기입니다. 처음 실행할 때 pdf_oxide_mcp를 자동으로 내려받으므로 MCP를 따로 설치할 필요가 없습니다.

Linux / macOS

curl -fsSL crgx.dev/install.sh | sh

Windows (PowerShell)

irm crgx.dev/install.ps1 | iex

설정

crgx를 설치한 뒤 아래 설정을 사용하는 AI 도구에 추가하면 됩니다. pdf_oxide_mcp의 다운로드와 업데이트는 crgx가 알아서 처리합니다.

Claude Desktop

~/.config/claude/claude_desktop_config.json (Linux) 또는 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)에 다음을 추가합니다.

{
  "mcpServers": {
    "pdf-oxide": {
      "command": "crgx",
      "args": ["pdf_oxide_mcp@latest"]
    }
  }
}

Claude Code

프로젝트의 .claude/settings.json에 추가합니다.

{
  "mcpServers": {
    "pdf-oxide": {
      "command": "crgx",
      "args": ["pdf_oxide_mcp@latest"]
    }
  }
}

Cursor

Cursor의 MCP 설정에 추가합니다.

{
  "mcpServers": {
    "pdf-oxide": {
      "command": "crgx",
      "args": ["pdf_oxide_mcp@latest"]
    }
  }
}

다른 설치 방법

crgx 대신 pdf_oxide_mcp를 직접 설치할 수도 있습니다.

Homebrew (macOS / Linux)

brew install yfedoseev/tap/pdf-oxide    # pdf-oxide-mcp 포함

Cargo

cargo install pdf_oxide_mcp

그다음 설정에서 바이너리 경로를 직접 지정합니다.

{
  "mcpServers": {
    "pdf-oxide": {
      "command": "pdf-oxide-mcp"
    }
  }
}

사용 가능한 도구

extract

PDF 파일에서 텍스트·Markdown·HTML을 추출합니다.

매개변수	타입	필수	설명
file_path	string	예	PDF 파일 경로
output_path	string	예	추출된 내용을 저장할 경로
format	string	아니요	"text" (기본값), "markdown", "html"
pages	string	아니요	페이지 범위 (예: "1-3,7,10-12")
password	string	아니요	암호화된 PDF의 비밀번호
images	boolean	아니요	이미지를 별도 파일로 출력물 옆에 저장
embed_images	boolean	아니요	markdown/html에 base64로 이미지 포함 (기본값: true)

동작 방식

MCP 서버는 stdio를 통해 JSON-RPC 2.0으로 통신합니다. AI 어시스턴트가 PDF를 읽어야 할 때는 tools/call 요청을 보내고 추출된 내용을 돌려받습니다.

모든 처리는 라이브러리·CLI와 동일한 Rust 추출 엔진을 써서 로컬에서 이루어집니다. 외부 서비스로 데이터가 전송되지 않습니다.

어시스턴트에게 건넬 수 있는 프롬프트

MCP 서버가 연결되면 어시스턴트가 스스로 extract를 호출합니다. 잘 동작하는 프롬프트 예시입니다.

• “report.pdf의 Markdown을 report.md로 저장해 주세요.”
• “contract.pdf의 4~8페이지를 이미지 임베드한 HTML로 contract.html에 저장해 주세요.”
• “bank-statement.pdf는 비밀번호 보호(pw: hunter2)예요 — 거래 내역 표만 텍스트로 뽑아 주세요.”

내부적으로 어시스턴트는 다음과 같은 JSON-RPC 호출을 보냅니다.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "extract",
    "arguments": {
      "file_path": "/path/report.pdf",
      "output_path": "/path/report.md",
      "format": "markdown",
      "pages": "4-8",
      "images": true,
      "embed_images": true
    }
  }
}

서버는 결과를 output_path에 기록하고 짧은 확인 메시지를 반환합니다. 어시스턴트는 그 파일을 다시 읽어 자신의 컨텍스트로 가져옵니다.