Claude Code의 PDF: 변환, 토큰, 구조 보존

Claude에서 PDF는 어떻게 처리되며, 페이지당 1,500–3,000토큰이 드는 이유는 무엇인가요?#

Anthropic의 공식 문서에서는 이 과정을 세 단계로 간단히 설명합니다.

논리적으로 들리지만, 처리 비용은 페이지 수에 비례해 증가합니다. PDF 하나만으로 구독 한도가 소진되는 이유를 설명하는 수치는 다음과 같습니다.

비용이 어느 정도인지 살펴보기 위해 Anthropic은 동일한 3페이지 PDF를 Bedrock에서 두 가지 방식으로 측정했습니다. 텍스트 모드(Converse Document Chat)에서는 ~1,000토큰을 사용했습니다. 시각 분석(Claude PDF Chat)에서는 ~7,000토큰을 사용했습니다. 이미지를 포함하면 처리 비용이 7배 더 높아집니다.

페이지 스크린샷은 더 많은 비용이 듭니다. 1000×1000픽셀 스크린샷은 약 1,300토큰이 듭니다.

원리는 간단합니다. Claude는 OCR을 완전히 신뢰하지 않기 때문에 PDF 처리 비용이 높습니다. 텍스트와 이미지를 모두 사용해 서로 비교하므로 두 레이어의 비용을 한꺼번에 지불하게 됩니다. 대용량 문서는 다르게 처리할 수 있습니다. 파일을 프로젝트 폴더에 Markdown으로 저장하고 Claude에게 “정보가 담긴 문서가 있으니 내용을 정리해 줘”라고 말하면 됩니다. 그러면 Claude는 한 번에 모든 내용을 소비하는 대신 자체 파일에 내용을 분산하고 정리된 텍스트로 계속 작업합니다.

일반적인 작업에서 PDF는 얼마나 많은 토큰을 사용하나요?#

구체적인 수치는 다음과 같습니다(Sonnet 4.x 모델, 입력 토큰 100만 개당 $3).

이는 요청 4회로 이루어진 한 주기만 계산한 것입니다. 이후에는 프롬프트 캐싱이 적용됩니다(기본 TTL 5분, 확장 등급에서는 최대 1시간, 해당 시간 내 반복 호출에 최대 90% 할인). 따라서 절약 효과가 커집니다.

새 채팅에서 같은 PDF를 업로드할 때마다 Claude는 파일을 다시 읽습니다. 캐시는 채팅 간에 유지되지 않습니다.

같은 15페이지 PDF를 한 번 Markdown으로 변환하고 네 개의 새 채팅마다 .md로 가져오면 이 예시는 135,000 대신 15 × 300 × 4 = 18,000 입력 토큰을 사용합니다. 변환 페이지당 300토큰과 PDF 페이지당 2,250토큰은 계산 가정이며 모든 PDF의 실측 상수가 아닙니다. 절약을 추정하기 전에 실제 문서 토큰을 세고 변환 품질을 확인하세요.

Claude Pro 구독에서는 이 계산이 더욱 중요합니다. 100페이지 보고서 하나가 5시간 한도를 모두 소진할 수 있습니다. Markdown으로 변환하면 같은 예산으로 이런 문서를 10개 이상 처리할 수 있습니다.

2026년 Anthropic API의 PDF 제한은 무엇인가요?#

Anthropic 문서에는 상단에 다음 제한이 나와 있습니다(2026년 5월 31일 기준).

Claude.ai(일반 사용자용 웹 앱)의 제한은 다릅니다. 파일당 최대 500 MB, 채팅당 최대 20개 파일을 허용합니다. 하지만 시각 분석은 최대 100페이지 PDF에서만 작동합니다. 그보다 긴 PDF에서는 Claude가 차트와 다이어그램 없이 텍스트만 볼 수 있습니다.

API로 PDF를 전송하는 방법은 세 가지입니다.

1. URL 사용 - "source": {"type": "url", "url": "..."} - 문서가 온라인에 있을 때 가장 간단합니다.
2. Base64 사용 - "source": {"type": "base64", "media_type": "application/pdf", "data": "..."} - 로컬 파일에 사용합니다.
3. Files API 사용 - "source": {"type": "file", "file_id": "file_abc123"} - 반복 요청에 사용하며, 베타 헤더 anthropic-beta: files-api-2025-04-14가 필요합니다.

같은 PDF를 서로 다른 채팅에서 작업할 때 Files API는 비용을 절약하는 주요 방법입니다. 한 번 업로드해 file_id를 받은 뒤 모든 상호작용에서 이를 사용합니다. cache_control: ephemeral을 설정하면 반복 호출 비용은 정가의 10%가 됩니다.

Anthropic은 사용량을 줄이는 공식 조언도 제공합니다.

방법 1: 5분 만에 MarkItDown을 설정하는 방법#

MarkItDown은 Microsoft의 공식 프로젝트이며 AutoGen 팀이 관리합니다. GitHub에서 스타 134천 개와 포크 9.2천 개를 받았습니다(2026년 5월 말 기준). README에는 목적이 다음과 같이 직접 설명되어 있습니다.

지원 형식:

• 문서: PDF, DOCX, PPTX, XLSX
• 웹: HTML, JSON, XML, CSV
• 미디어: 전사가 포함된 오디오, EXIF 및 OCR이 포함된 이미지, YouTube 동영상(자막 사용)
• 아카이브: ZIP, EPub
• 기타: Outlook MSG 파일에 포함된 모든 첨부 파일

설치

요구 사항: Python 3.10+(macOS에는 보통 이미 설치되어 있습니다. Windows에서는 별도로 설치해야 합니다).

pip install 'markitdown[all]'

모든 형식이 필요하지 않다면 필요한 형식만 설치할 수 있습니다.

pip install 'markitdown[pdf, docx, pptx]'

단일 파일 변환

가장 간단한 방법입니다.

markitdown document.pdf > document.md

그러면 현재 폴더에 document.md가 생깁니다. @document.md를 사용해 Claude Code에 추가하거나 프로젝트 옆에 놓으면 됩니다.

Python API

스크립트에 통합하려면 다음과 같이 합니다.

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("research-paper.pdf")
print(result.text_content)

# 바로 저장할 수도 있습니다:
with open("research-paper.md", "w") as f:
    f.write(result.text_content)

MarkItDown으로 할 수 없는 작업

• 스캔 PDF OCR - 결과가 반환되지 않습니다. 스캔본에는 PyMuPDF4LLM 또는 Docling이 필요합니다.
• 복잡한 다단 레이아웃 - 읽기 순서가 뒤섞일 수 있습니다.
• PDF에 포함된 URL - 보존하지 않습니다.

보고서, 기사, 문서와 같은 일반 PDF에는 MarkItDown이 가장 좋습니다. 설치가 1분이면 끝나는 다용도 도구이며 Python 지식도 필요하지 않습니다. 키릴 문자가 포함된 문서와 스캔본에서의 성능은 AI용 PDF 텍스트 변환 분석의 측정 결과에 나와 있습니다.

방법 2: PyMuPDF4LLM은 어떤 기능을 제공하며, 어떤 경우에 더 적합한가요?#

MarkItDown은 다양한 형식을 폭넓게 지원하고, PyMuPDF4LLM은 PDF를 깊이 있게 처리합니다.

2026년 5월 31일 기준 버전은 1.27.2.3입니다(2026년 4월 24일 출시).

포함 기능

• 올바른 읽기 순서를 적용한 다단 페이지 처리
• GitHub Flavored Markdown으로 표 변환
• 머리글과 바닥글 자동 제거
• 이미지를 추출해 별도 폴더에 상대 링크로 저장
• 스마트 OCR: 읽을 수 없는 영역에만 적용해 처리 시간 ~50% 절약
• 네이티브 C 엔진, GPU 불필요

설치

pip install pymupdf4llm

사용법

import pymupdf4llm

# 기본 사용법 - 바로 Markdown으로 변환:
md_text = pymupdf4llm.to_markdown("document.pdf")

# 저장:
with open("document.md", "w") as f:
    f.write(md_text)

약속한 대로 한 줄로 실행할 수도 있습니다.

python3 -c "import pymupdf4llm; \
  open('document.md','w').write(pymupdf4llm.to_markdown('document.pdf'))"

MarkItDown 대신 PyMuPDF4LLM을 선택할 경우

• 보존해야 할 링크가 PDF에 많은 경우(MarkItDown은 링크를 잃습니다).
• 문서가 스캔본이고 OCR이 필요한 경우.
• 로컬에서 수천 개 파일을 빠르게 처리해야 하는 경우. 네이티브 C 엔진이 Python 래퍼보다 빠릅니다.
• 추가 처리를 위해 PDF의 이미지를 별도 폴더에 저장해야 하는 경우.

라이선스 세부 정보(비즈니스에 중요)

PyMuPDF4LLM은 AGPL v3 또는 Artifex 상용 라이선스로 제공됩니다.

AGPL의 의미: 공개 SaaS에서 이 라이브러리를 사용하면 서비스의 전체 소스 코드를 동일한 AGPL 라이선스로 공개해야 합니다. 내부 사용(노트북에서 실행하는 스크립트)에는 제한이 없습니다.

코드를 공개하지 않고 상업적으로 개발하려면 Artifex(artifex.com)에서 라이선스를 구매하세요. 가격은 공개되어 있지 않으므로 영업팀에 문의해야 합니다.

고객용 제품을 만든다면 초기에 라이선스를 확인하세요. MarkItDown(MIT)과 Docling(MIT)은 SaaS에 더 안전한 선택입니다.

방법 3: Claude Code MCP 설정으로 MarkItDown 서버에 연결하기#

CLI 모드의 MarkItDown은 “파일을 미리 직접 변환한다”는 뜻이고, MCP 서버는 “Claude Code가 변환 시점을 결정한다”는 뜻입니다.

설치

uv 패키지 관리자가 필요합니다. 서버를 별도로 설치할 필요는 없습니다. uv가 처음 실행될 때 다운로드합니다.

Claude Code 설정

명령 하나로 버전을 고정해 모든 프로젝트에 서버를 연결할 수 있습니다.

claude mcp add --scope user --env 'ORT_DISABLE_TELEMETRY=1' --env 'UV_PYTHON=3.12' --transport stdio markitdown -- uvx markitdown-mcp@0.0.1a7
claude mcp list

markitdown 항목에 “Connected”라고 표시되어야 합니다. 처음 시작할 때 패키지 약 70개를 다운로드하므로 최대 1분이 걸립니다. 이후에는 서버가 1~2초 만에 시작됩니다.

명령에 두 변수가 필요한 이유는 다음과 같습니다. ORT_DISABLE_TELEMETRY=1은 서버 내부의 onnxruntime 엔진이 Mac과 Linux에서 기본적으로 Microsoft에 전송하는 통계를 비활성화합니다. UV_PYTHON=3.12는 Windows, Linux 및 Apple Silicon Mac에서 사전 빌드된 패키지를 사용할 수 있는 Python 3.12로 서버를 실행합니다. Intel Mac과 macOS 13 및 이전 버전에서는 Python 3.14로 서버를 설치할 수 없습니다. Intel과 3.12 조합에는 주의할 점이 있습니다. 2026년 6월 이후 사전 빌드된 Intel 패키지가 없어서 uv가 cryptography 라이브러리를 소스에서 빌드합니다. 설치 시간이 길어지고 실패할 수도 있습니다. Python 3.12가 없다면 uv가 다운로드합니다.

서버는 컴퓨터에서 직접 실행되며 사용자가 접근할 수 있는 모든 파일을 열 수 있습니다. Claude Code가 열려 있었다면 다시 시작하세요. 그러면 MCP 서버 목록에 markitdown이 나타납니다.

사용법

Claude Code에서 다음과 같이 말하면 됩니다.

/Users/your-user/Documents/report.pdf를 Markdown으로 변환하고 핵심 내용을 분석해 주세요.

Claude는 직접 convert_to_markdown(uri)를 호출해 Markdown을 받은 뒤 작업합니다. PDF 자체는 컨텍스트에 로드되지 않습니다.

지원 URI

• file:// - 로컬 파일
• http://, https:// - 온라인 문서
• data: - 인라인 데이터(Base64)

보안

공식 README에서 발췌:

기본 설정에서는 localhost에 바인딩됩니다. HTTP/SSE로 실행할 경우(--http --host 127.0.0.1 --port 3001 옵션), 인증된 리버스 프록시 없이 포트를 외부에 노출하지 마세요.

작업에 어떤 방법을 선택해야 할까요?#

상세 비교표:

Marker는 벤치마크에서 인상적인 정확도 수치를 공개합니다.

하지만 Marker는 빠르게 처리하려면 GPU가 필요하고 머신러닝 모델도 함께 설치해야 합니다. 일반 텍스트 PDF와 같은 대부분의 작업은 PyMuPDF4LLM이나 MarkItDown으로 GPU 없이 몇 초 만에 처리할 수 있습니다.

간단한 선택 기준

1. PDF 한두 개를 빠르게 처리해야 함 - MarkItDown CLI.
2. PDF 수십 개를 자동화해야 함 - MarkItDown MCP 서버 또는 스크립트에서 PyMuPDF4LLM 사용.
3. 링크와 이미지가 포함되어 구조 보존이 중요한 PDF - PyMuPDF4LLM.
4. 표의 안정성이 중요한 비즈니스용 프로덕션 RAG - Docling.
5. 수식이 포함된 과학 논문 - Marker.
6. 직접 신경 쓰고 싶지 않아 Claude가 변환하길 원함 - MarkItDown MCP 서버.

문서 폴더를 자동으로 변환하는 재사용 가능한 스크립트는 어떻게 작성하나요?#

실제 예를 들어 보겠습니다. 중개 계좌 명세서, 계약서, 발표 자료 등 고객의 PDF 및 PPTX 보고서 40개가 한 폴더에 있다고 가정해 보세요. 폴더를 Claude에 바로 업로드하는 것은 소용이 없습니다. 첫 답변을 받기도 전에 컨텍스트 창이 정보로 가득 찰 테니까요. 아래 스크립트로 폴더 전체를 한 번에 처리한 다음, 용량이 큰 PDF 대신 가벼운 .md 파일로 계속 작업하세요.

프로젝트 루트의 scripts/docs-to-md.sh에 다음 스크립트를 저장하세요.

#!/bin/bash
# docs-to-md.sh - MarkItDown을 사용해 폴더의 모든 문서를 Markdown으로 변환합니다
# 사용법: bash docs-to-md.sh ./documents

set -e

INPUT_DIR="${1:-./documents}"
OUTPUT_DIR="${INPUT_DIR}/_md"

mkdir -p "$OUTPUT_DIR"

echo "Scanning $INPUT_DIR..."

for file in "$INPUT_DIR"/*.{pdf,docx,pptx,xlsx}; do
  [ -f "$file" ] || continue

  basename=$(basename "$file")
  name="${basename%.*}"
  output="$OUTPUT_DIR/${name}.md"

  if [ -f "$output" ] && [ "$output" -nt "$file" ]; then
    echo "Skipping $basename (already converted)"
    continue
  fi

  echo "Converting $basename..."
  markitdown "$file" > "$output"
done

echo "Done. Results are in $OUTPUT_DIR"

실행 권한을 부여합니다.

chmod +x scripts/docs-to-md.sh

실행합니다.

bash scripts/docs-to-md.sh ./reports

실행이 끝나면 ./reports/_md/에 모든 문서의 .md 버전이 들어 있습니다. @reports/_md/를 사용해 Claude Code에 추가하고 PDF 대신 압축된 텍스트로 작업하세요.

스크립트는 이미 변환된 파일을 자동으로 건너뜁니다(.md 파일이 원본보다 최신인 경우). 다시 실행해도 빠르게 끝나며 모든 내용을 다시 계산하지 않습니다.

멱등성 및 증분 변환

같은 이름으로 다시 저장된 PDF의 변경 사항도 스크립트가 감지하길 원한다면 콘텐츠 해시 검사를 추가하세요.

hash=$(shasum -a 256 "$file" | cut -d' ' -f1)
hash_file="$OUTPUT_DIR/.${name}.sha256"

if [ -f "$hash_file" ] && [ "$(cat "$hash_file")" = "$hash" ]; then
  echo "Skipping $basename (hash matches)"
  continue
fi

markitdown "$file" > "$output"
echo "$hash" > "$hash_file"

이 버전은 콘텐츠가 변경된 경우에만 파일을 다시 변환합니다.

Markdown보다 Claude에서 PDF를 사용하는 편이 나은 경우는 언제인가요?#

Markdown 변환이 부족한 경우는 세 가지입니다.

1. 다이어그램과 차트의 시각 분석

Claude가 가격 곡선, 프로세스 다이어그램 또는 아키텍처 다이어그램 같은 차트를 “읽어야” 한다면, 그 정보는 Markdown에 없습니다. Markdown에는 그림 설명만 남고 그림 자체는 사라집니다.

해결 방법: PDF를 업로드하고 시각 모드를 명시적으로 활성화하세요. Claude API에서는 해당 플래그가 자동으로 작동하지만, AWS Bedrock에서는 citations 플래그가 필요합니다.

2. 병합 셀이 있는 복잡한 표

Markdown 표는 평면적입니다. PDF에 병합 셀, 여러 단계의 헤더 또는 중첩 표가 있으면 변환기가 표를 평면화하거나 관계를 잃게 됩니다.

해결 방법: PDF를 직접 사용하거나, 복잡한 표를 가장 잘 처리하는 Docling을 사용하거나, 변환 후 수동으로 서식을 정리하세요.

3. 페이지 참조가 필요한 문서 산출물

법률 문서, 계약서, 회의록에서는 “7페이지 3항”처럼 인용할 수 있어야 합니다. Markdown에서는 페이지 번호가 사라집니다.

해결 방법: PDF + Files API + 프롬프트 캐싱을 사용하세요. 한 번 업로드한 뒤 file_id로 참조하면 Claude가 페이지 구성을 확인하고 특정 페이지를 인용할 수 있습니다.

짧은 문서

PDF가 2페이지 미만이고 한 번만 사용한다면 변환할 필요가 없습니다. PDF는 5,000토큰, Markdown은 800토큰이지만 MarkItDown을 설치할 만큼 절약되는 것은 아닙니다.

손익분기점은 약 5페이지 이상이거나 동일한 문서를 2회 이상 사용하는 경우입니다. 이보다 적으면 PDF를 직접 업로드하고, 이보다 많으면 변환하세요.

Claude에서 PDF를 사용할 때 흔히 저지르는 5가지 실수는 무엇인가요?#

1. 새 채팅마다 같은 PDF를 업로드하기

Claude Pro에는 5시간 동안의 메시지 한도가 있습니다. 50페이지 보고서 하나가 두 번째 질문을 하기도 전에 한도를 모두 사용할 수 있습니다.

간단한 원칙이 있습니다. 작업 하나당 채팅 하나입니다. AI가 터무니없이 많은 토큰을 사용하기 시작한다면 모든 내용을 한 채팅에 몰아넣고 PDF를 계속 가져오고 있다는 뜻입니다. 각 창에서는 작은 작업 하나만 처리하세요. 문서를 한 번만 Markdown으로 변환한 뒤 새 창을 열 때마다 프로젝트와 함께 .md 파일을 추가하세요. 컨텍스트 창 표시 원이 노란색으로 변하지 않을 것입니다.

해결 방법: 한 번 Markdown으로 변환하거나 file_id와 프롬프트 캐싱을 함께 사용하세요.

2. 텍스트 대신 스크린샷 사용하기

흔한 예를 들어 보겠습니다. Claude에게 코드나 표를 보여주려고 1920×1080 화면 전체를 스크린샷으로 찍은 뒤, 요청 5회 만에 한도가 소진된 이유를 궁금해합니다.

1000×1000픽셀 스크린샷은 ~1,300토큰이 듭니다. 같은 내용을 직접 복사하면 50–100토큰입니다. 13–26배 차이입니다.

해결 방법: 스크린샷을 중요한 부분만 남도록 정밀하게 자르세요. 더 좋은 방법은 텍스트를 직접 복사하는 것입니다.

3. OCR을 적용하지 않은 스캔 PDF

MarkItDown은 OCR을 할 수 없습니다. 스캔본을 변환하면 .md 파일이 비어 있거나 잡음이 담긴 3줄만 생깁니다.

해결 방법: 스캔본에는 스마트 OCR이 내장된 PyMuPDF4LLM 또는 Docling을 사용하세요.

4. 100페이지 제한 무시하기

Anthropic 문서에는 요청당 600페이지 제한이 나와 있지만, 실제로 컨텍스트가 200K인 모델(Sonnet 4.x, Opus 4.x)의 제한은 100페이지입니다. 600페이지 제한은 구형 모델이나 특별 등급을 위한 것입니다.

150페이지 보고서를 Sonnet 4.6에 업로드하면 오류가 발생하거나, 더 나쁘게는 Claude가 처음 100페이지만 처리하고 문서 전체를 읽은 것처럼 답할 수 있습니다.

해결 방법: 긴 PDF는 업로드 전에 여러 부분으로 나누세요. 또는 Markdown으로 변환하세요. 페이지 제한은 없고 토큰 제한만 있습니다.

5. 반복 요청에 프롬프트 캐싱을 사용하지 않기

API를 통해 같은 문서로 작업한다면 cache_control: ephemeral로 감싸세요. 5분 이내 반복 호출 비용은 최초 가격의 10%입니다. 첫 요청은 더 비싸지만 이후 요청에는 90% 할인이 적용됩니다.

해결 방법: 한 번 이상 업로드하는 모든 항목에 프롬프트 캐싱을 기본적으로 활성화하세요.

다음 단계: 컨텍스트 엔지니어링#

PDF를 Markdown으로 변환하는 것은 토큰을 절약하는 한 가지 방법입니다. 이것만으로 Claude의 답변이 더 정확해지지는 않습니다. 정확도는 질문하기 전에 모델의 컨텍스트에 무엇을 넣을지 정하는 분야인 컨텍스트 엔지니어링에서 나옵니다.

CLAUDE.md에 800줄이 있고, 프로젝트에 불필요한 MCP 서버가 10개 있으며, 100페이지 PDF까지 가져온다면 Markdown 변환으로 누수 하나를 막을 수는 있지만 나머지 세 가지는 그대로입니다. 그래서 다음 가이드에서 이 내용을 다룹니다.

• Claude Code에서 토큰이 사용되는 곳 - PDF뿐 아니라 컨텍스트 누수의 9가지 패턴.
• 2026년의 컨텍스트 엔지니어링 - 컨텍스트를 체계적으로 관리하는 방법.
• Claude Code의 Plan Mode - Claude가 코드 작성을 시작하기 전에 사용하는 계획 모드.