Claude PDF 토큰 절약: MarkItDown 설치·사용법과 MCP 연결

Claude에 넣을 PDF가 글자 위주라면, MarkItDown으로 마크다운(Markdown) 파일로 바꿔 보세요. 이미지와 텍스트를 함께 처리하는 PDF 경로에서, 시각 정보가 필요 없는 질문의 입력을 줄이는 방법입니다. 차트·도면·스캔 이미지가 핵심이라면 원본 확인이나 별도의 문자 인식이 필요합니다.

쇼츠에서 “PDF 대신 Markdown을 올리면 토큰을 아낄 수 있다”고 소개했는데요. 실제로 따라 하려면 설치 명령어 외에도 알아둘 것이 있습니다. 어떤 문서에 유리한지, 변환 과정에서 무엇이 빠지는지, 파일을 매번 올리지 않고 연결해 읽는 방법까지 차례로 정리했습니다.

MarkItDown이란? PDF를 마크다운으로 변환하는 도구

MarkItDown은 Microsoft가 공개한 문서 → Markdown 변환 도구입니다. PDF·Word·PowerPoint·Excel 등의 내용을 텍스트 중심으로 추출해 AI에게 전달하거나 검색·분석에 활용할 수 있습니다. MIT 라이선스의 오픈소스이며, 기본 로컬 변환에 유료 AI API 키는 필요하지 않습니다. Microsoft 공식 저장소

Markdown은 제목·목록·표 등을 간단한 문자 기호로 표현하는 형식입니다. 보통 확장자는 .md입니다. 예를 들어 다음 내용도 Markdown입니다.

# 제품 설명서

## 충전 방법
- 전원을 끈 뒤 충전 케이블을 연결합니다.
- 충전 표시등을 확인합니다.

| 항목 | 확인할 내용 |
| --- | --- |
| 충전 단자 | USB-C |

위 예시는 형식을 설명하기 위해 만든 내용입니다. 실제 변환 결과가 항상 이렇게 깔끔한 것은 아닙니다. PDF에서는 제목 구조가 사라지거나 문장 중간에 줄바꿈이 남을 수 있습니다.

또한 변환은 요약이 아닙니다. 긴 문서를 짧게 써주는 작업이 아니라, 읽을 수 있는 내용을 다른 형식으로 옮기는 작업입니다. 요약은 변환 결과를 확인한 뒤 Claude에게 요청합니다.

왜 PDF를 Markdown으로 바꾸면 토큰을 줄일 수 있나요?

PDF를 이미지와 텍스트로 함께 처리하는 경우, 텍스트만 전달하면 페이지 이미지에 쓰이는 입력을 줄일 수 있기 때문입니다. 토큰은 AI가 입력과 출력을 처리할 때 쓰는 단위입니다. 파일 용량인 MB·KB와는 다릅니다.

Anthropic의 API 문서는 시각 PDF 처리에서 각 페이지를 이미지로 만들고, 추출한 텍스트도 함께 제공한다고 설명합니다. 이 경로에서는 텍스트 처리량 외에 이미지 처리량이 더해집니다. 문서는 페이지당 텍스트를 통상 1,500~3,000토큰으로 안내하지만, 밀도에 따라 달라지는 추정치입니다. 모든 PDF 페이지의 고정 사용량이나 Markdown 변환 후의 절약량을 뜻하지는 않습니다. Claude API의 PDF 처리 설명

다만 “Claude는 모든 PDF를 언제나 두 번 읽는다”라고 이해하면 부정확합니다. Claude 앱 도움말은 100쪽 이하 PDF는 텍스트와 시각 정보를 분석하고, 101~1,000쪽은 텍스트만 처리한다고 구분합니다. 이미 텍스트만 추출하는 경로라면 이미지 입력을 없애는 효과는 기대하기 어렵습니다. Claude 파일 업로드 도움말

파일이 작아진 비율이 토큰 절약률은 아닙니다

쇼츠에서 소개한 변환 예시에서는 PDF가 약 3.0MB, 변환한 .md 파일이 약 40KB로 표시됩니다. 텍스트 파일이 훨씬 작아졌다는 사례이지, 토큰이나 구독 사용량이 같은 비율로 줄었다는 측정 결과는 아닙니다.

비교해야 할 것은 세 가지입니다.

• 파일 크기: 저장하거나 업로드하는 데이터의 양입니다.
• 입력 토큰: 실제로 AI에 전달되는 텍스트·이미지 등의 처리량입니다.
• 답변 품질: 필요한 표·조건·수치가 남아 있어 같은 질문에 답할 수 있는지입니다.

Claude 구독의 사용량은 메시지·첨부 파일·대화 길이·사용 기능 등의 영향을 받으므로, API 토큰 수를 남은 대화 횟수로 그대로 환산할 수 없습니다. “70% 절약”, “대화 횟수 3배” 같은 수치 대신 내 문서에서 필요한 정보가 유지되는지부터 확인하세요. Claude 사용량 관리 안내

어떤 PDF는 변환하고, 어떤 PDF는 원본을 올려야 하나요?

문서 이름보다 질문에 필요한 정보의 형태로 고르세요. 같은 보고서라도 본문 요약은 Markdown이 편하고, 그래프의 추세 비교는 원본 이미지가 필요합니다.

추천하는 첫 실습은 글자를 드래그해 복사할 수 있는 짧은 PDF 한 개입니다. 변환 전 원본에서 질문 하나와 답의 근거를 정해 두세요. 변환 후에도 그 근거가 남아 있다면 다음 문서로 확장하기 좋습니다.

OCR은 이미지 속 글자를 텍스트로 읽는 기능입니다. 스캔 PDF라도 이미 OCR 텍스트가 덧붙여진 파일이라면 일반 텍스트 추출로 읽힐 수 있습니다. 파일이 만들어진 방식보다 실제로 선택·복사되는 글자가 있는지 확인하는 이유입니다.

방법 1. MarkItDown 설치부터 PDF 변환까지

작업 폴더 준비 → 설치 → 변환 → 결과 확인 → Claude에 첨부 순서입니다. 설치는 한 번 하고, 다음부터는 변환만 반복하면 됩니다.

1. Python과 작업 폴더를 준비하세요

확인한 MarkItDown 0.1.8과 공식 저장소는 Python 3.10~3.14를 지원 범위로 안내합니다. Python 다운로드에서 해당 범위의 버전을 설치하세요. 아래는 다른 프로그램과 패키지가 섞이지 않도록 작업 폴더 안에 가상환경을 만드는 방식입니다. 가상환경은 이 도구만 사용할 별도의 설치 공간이라고 생각하면 됩니다. MarkItDown 요구 사항 · Python 가상환경 안내

컴퓨터의 문서 폴더에 markitdown-work 폴더를 만들고, 변환할 파일을 설명서.pdf라는 이름으로 넣습니다. 아래 명령을 한 줄씩 실행하세요. 다른 위치에 만들었다면 cd 뒤 경로를 바꿉니다. 폴더 이동에 실패하거나 Python 버전이 지원 범위 밖이라면 다음 줄로 넘어가지 말고 먼저 해결하세요.

cd "$HOME/Documents/markitdown-work"
python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "markitdown[all]"
python -m markitdown --version

cd /d "%USERPROFILE%\Documents\markitdown-work"
py -3 --version
py -3 -m venv .venv
.venv\Scripts\activate.bat
python -m pip install "markitdown[all]"
python -m markitdown --version

마지막에 MarkItDown 버전이 나오면 실행 준비가 된 것입니다. [all]은 지원 형식에 필요한 선택 의존성을 함께 설치하는 옵션입니다. 스캔 PDF의 OCR까지 자동으로 설정해 준다는 뜻은 아닙니다. 설치·선택 의존성 안내

2. PDF를 Markdown으로 변환하세요

가상환경이 켜진 상태에서 실행합니다. macOS와 Windows 모두 같습니다.

python -m markitdown "설명서.pdf" -o "설명서.md"

-o 뒤에는 저장할 파일 이름을 적습니다. 원본 PDF는 남고, 같은 폴더에 설명서.md가 만들어집니다. 출력 이름에 같은 파일이 이미 있으면 덮어쓸 수 있으므로 보관할 결과는 다른 이름을 사용하세요.

파일 이름에 공백이 있어도 따옴표로 감싸면 됩니다.

python -m markitdown "10월 업무 보고서.pdf" -o "10월 업무 보고서.md"

3. 파일이 생겼는지보다 내용이 남았는지 확인하세요

.md 파일을 텍스트 편집기로 열어 처음·중간·끝을 확인합니다. 다음 명령으로 앞부분을 볼 수도 있습니다.

python -c "from pathlib import Path; print(Path('설명서.md').read_text(encoding='utf-8')[:1000])"

• 문서의 핵심 문장이 남아 있나요?
• 중요한 표의 숫자와 단위가 같은 항목에 붙어 있나요?
• 한글이 깨지거나 본문이 거의 비어 있지는 않나요?

변환 예시 화면에서도 문장 중간 줄바꿈과 페이지 머리말이 남아 있었습니다. 파일이 작아진 것만으로 변환 품질까지 좋다고 판단하지 마세요.

4. Claude에 변환본을 첨부하세요

새 채팅에 설명서.md를 끌어다 놓고 질문합니다. 사용하는 화면에서 .md 첨부가 거부되면 내용은 그대로 둔 .txt 사본을 만들어 올리세요. TXT는 공식 업로드 지원 형식입니다. 파일 첨부 안내

python -c "from pathlib import Path; p=Path('설명서.md'); p.with_suffix('.txt').write_text(p.read_text(encoding='utf-8'), encoding='utf-8')"

이 명령도 같은 이름의 설명서.txt가 있으면 덮어씁니다. 기존 TXT가 필요하면 먼저 다른 이름으로 보관하세요.

PDF가 이미 들어 있는 채팅에서 .md를 추가한다고 기존 입력이 없어지는 것은 아닙니다. 변환본만으로 작업하려면 새 채팅에서 변환본을 첨부하는 편이 분명합니다.

복사해서 사용할 요약 프롬프트입니다.

첨부한 문서는 PDF에서 추출한 텍스트입니다.
이 파일에 있는 내용만 근거로 다음을 정리해 주세요.

1. 핵심 내용 5가지
2. 내가 실행해야 할 일과 각 항목의 근거 문장
3. 숫자·날짜·조건을 원문 표현대로 모은 표
4. 내용이 끊기거나 표·그림이 빠져 원본 확인이 필요한 부분

모르는 내용은 추측하지 말고 '변환본에서 확인 불가'라고 표시하세요.
페이지 번호가 남아 있지 않으면 임의의 페이지 번호를 만들지 마세요.

Word·PowerPoint·Excel·YouTube도 변환할 수 있나요?

네. 파일 형식별로 지원하는 변환기를 사용합니다. 아래는 앞에서 설치한 가상환경에서 실행하는 예시입니다. 파일 이름과 VIDEO_ID를 실제 값으로 바꿔 사용하세요.

지원한다는 사실이 모든 형식에서 PDF와 같은 토큰 절약 효과가 난다는 뜻은 아닙니다. Claude 앱은 PDF가 아닌 문서에서 텍스트만 추출한다고 안내합니다. Word·Excel 변환은 필요한 내용 정리와 재사용에 초점을 맞추세요. 문서 형식별 처리 안내

python -m markitdown "기획안.docx" -o "기획안.md"
python -m markitdown "강의자료.pptx" -o "강의자료.md"
python -m markitdown "매출자료.xlsx" -o "매출자료.md"
python -m markitdown "https://www.youtube.com/watch?v=VIDEO_ID" -o "영상.md"

YouTube 변환은 영상 화면을 시청해 해설하는 기능이 아닙니다. 자막 제공 여부, 언어, 접근 제한에 따라 실패할 수 있습니다. .md가 생성되어도 제목·설명만 있고 자막은 없을 수 있으니 자막 본문이 들어 있는지 확인하세요. YouTube 변환기 구현

방법 2. Claude Code에 설치와 변환을 말로 맡기기

터미널 명령이 낯설다면 Claude Code가 작업 폴더에서 설치·변환을 수행하도록 요청할 수 있습니다. Claude Desktop의 Code 탭을 이용하는 방법입니다. 공식 시작 안내는 Pro·Max·Team·Enterprise 구독을 명시합니다. 조직 계정은 관리자가 허용한 사용 범위도 확인하세요. Code 탭 시작 안내

1. Claude Desktop을 열고 Code 탭으로 이동합니다.
2. Environment는 Local, Project folder는 markitdown-work 폴더로 선택합니다.
3. 모델은 사용할 수 있는 기본 모델로 두고, 작업 내용을 확인하며 진행하려면 Permission mode를 Manual로 선택합니다.
4. 변환할 PDF를 그 폴더에 넣고 아래 프롬프트를 보냅니다.

메뉴 이름은 앱 버전에 따라 달라질 수 있습니다. 확인해야 할 핵심은 내 컴퓨터에서 실행되는지, 선택한 폴더가 맞는지입니다. 환경·권한 모드 안내

설치부터 결과 검수까지 맡기는 프롬프트

이 작업 폴더의 '설명서.pdf'를 MarkItDown으로 변환해 주세요.

1. 운영체제와 Python 버전을 확인하세요.
2. Python 3.10~3.14가 있으면 이 폴더의 .venv를 사용하거나 생성하세요.
3. 그 가상환경에 markitdown[all]을 설치하세요.
4. 원본 PDF는 그대로 두고 '설명서.md'로 저장하세요.
   같은 이름의 결과 파일이 있으면 덮어쓰지 말고 새 이름을 사용하세요.
5. 저장 경로, 파일 크기, 내용 앞부분을 보여 주세요.
6. 비어 있는 결과·깨진 한글·흐트러진 표·누락이 의심되는 부분을 점검하세요.
   원본과 대조하지 않은 부분은 '미검증'으로 표시하고, 내용이 모두 보존됐다고 단정하지 마세요.

PDF를 먼저 시각 분석 도구로 읽지 말고 로컬 변환 명령부터 실행하세요.
시스템 Python을 수정하거나 sudo, --break-system-packages를 쓰지 마세요.
Python 설치가 필요하면 내 운영체제에 맞는 공식 설치 방법을 먼저 알려 주세요.

실행이나 파일 변경 확인 창이 나오면 대상 경로와 명령을 확인합니다. 완료 후에는 실제로 생성된 파일을 열어보세요. 변환본을 새 Chat 대화에 첨부하거나, Code 세션에 그 파일만 읽고 분석해 달라고 요청할 수 있습니다.

다음 문서부터는 짧게 요청하면 됩니다.

같은 가상환경을 사용해서 '회의록.pdf'를 '회의록.md'로 변환해 주세요.
원본과 기존 결과 파일은 덮어쓰지 마세요.
변환한 파일을 읽고 결정 사항·담당자·기한을 표로 정리하세요.
문서에 없는 담당자나 기한은 '미정'으로 표시하세요.

방법 3. MarkItDown MCP를 Claude Desktop에 연결하기

MCP를 연결하면 Claude가 도구를 호출해 문서를 Markdown 텍스트로 받아올 수 있습니다. 파일을 자주 바꾸며 읽는 분에게 편리합니다. 가끔 변환한다면 앞의 명령어 방식만으로도 충분합니다.

MCP(Model Context Protocol)는 AI 앱과 외부 도구를 연결하는 규약입니다. 이 글에서는 Claude Desktop과 내 컴퓨터에서 실행하는 MarkItDown 변환 도구를 연결합니다.

먼저 구분할 점이 있습니다. 공식 markitdown-mcp의 convert_to_markdown은 변환한 텍스트를 반환하는 도구입니다. 연결만으로 내 폴더에 .md 파일이 자동 저장되는 것은 아닙니다. 파일 보관이 목적이라면 앞의 CLI 또는 파일 저장이 가능한 도구를 함께 사용하세요. MCP 도구 구현

1. 같은 가상환경에 MCP 패키지를 설치하세요

방법 1의 작업 폴더와 가상환경에서 실행합니다.

python -m pip install markitdown-mcp
python -m markitdown_mcp --help
python -c "import sys; print(sys.executable)"

마지막 명령이 출력한 가상환경 Python의 전체 경로를 복사합니다. Claude Desktop이 어떤 Python을 실행할지 명확히 지정하기 위해서입니다.

확인한 markitdown-mcp 버전은 0.0.1a7로, PyPI에서 사전 출시 버전으로 표시합니다. 실행 확인은 이 버전 기준이며 이후 릴리스에서는 동작이 달라질 수 있습니다. 검증한 MCP 패키지 버전

2. Claude Desktop 설정에 서버를 추가하세요

앱 설정의 Developer → Edit Config에서 claude_desktop_config.json을 엽니다. 웹 계정 설정이 아니라 데스크톱 앱 설정입니다. 로컬 MCP 서버 연결 안내

아래는 macOS 경로 예시입니다. command를 방금 복사한 실제 경로로 바꾸세요. 기존 mcpServers가 있다면 그 안에 markitdown 항목만 추가하고, 다른 서버 설정은 유지합니다.

{
  "mcpServers": {
    "markitdown": {
      "command": "/Users/YOUR_NAME/Documents/markitdown-work/.venv/bin/python",
      "args": ["-m", "markitdown_mcp"]
    }
  }
}

Windows에서는 command가 다음 형태가 됩니다. JSON의 역슬래시는 두 번 적습니다.

{
  "mcpServers": {
    "markitdown": {
      "command": "C:\\Users\\YOUR_NAME\\Documents\\markitdown-work\\.venv\\Scripts\\python.exe",
      "args": ["-m", "markitdown_mcp"]
    }
  }
}

공식 MCP README는 Docker 실행을 권장합니다. 여기서는 앞서 설치한 Python 환경을 재사용해 로컬 표준 입출력 방식으로 연결합니다. 이 방식은 실행 사용자에게 읽기 권한이 있는 파일에 접근할 수 있으며, 작업 폴더 밖의 접근을 자동으로 차단하지는 않습니다. 폴더 접근 범위를 격리해야 한다면 공식 Docker 구성과 폴더 마운트 방식을 참고하세요. MarkItDown MCP 공식 안내

3. 앱을 재시작하고 도구를 확인하세요

Claude Desktop을 완전히 종료했다가 다시 실행합니다. 연결 목록에서 markitdown과 convert_to_markdown 도구가 보이는지 확인합니다.

도구가 받는 값은 단순 파일 이름이 아니라 URI입니다. 로컬 파일은 file:///로 시작하는 주소를 사용합니다. 다음 명령은 현재 폴더의 설명서.pdf를 URI로 바꿔 출력합니다. 공백과 한글도 주소에 맞게 처리합니다.

python -c "from pathlib import Path; print(Path('설명서.pdf').resolve().as_uri())"

출력된 URI를 아래 프롬프트에 넣으세요.

MarkItDown의 convert_to_markdown 도구로 다음 파일을 변환해 읽어 주세요.
파일 URI: 여기에_출력된_file_URI_붙여넣기

반환된 텍스트를 근거로 핵심 내용 5개와 실행할 일 3개를 정리하세요.
표·그림이 빠져 판단할 수 없는 부분은 별도로 표시하세요.
도구 호출이 실패하면 실패 이유를 알려 주고 내용을 추측하지 마세요.

이 연결은 내 컴퓨터의 Claude Desktop에서 실행되는 로컬 MCP입니다. 같은 파일 경로가 모바일이나 웹에서도 자동으로 열리는 것은 아닙니다. 또한 MCP로 읽어온 텍스트도 AI의 입력이므로 토큰 사용량은 남습니다.

여러 문서를 반복 변환한다면: Python 코드 예제

폴더의 문서를 일괄 변환해 markdown 하위 폴더에 모을 수 있습니다. 아래 코드를 작업 폴더의 convert_docs.py로 저장하세요. 원본을 수정하지 않고, 기존 결과는 건너뛰며, 비어 있는 결과는 저장하지 않는 예제입니다.

from pathlib import Path
from markitdown import MarkItDown

root = Path(__file__).resolve().parent
output_dir = root / "markdown"
output_dir.mkdir(exist_ok=True)
converter = MarkItDown(enable_plugins=False)
extensions = {".pdf", ".docx", ".pptx", ".xlsx"}

for source in sorted(root.iterdir()):
    if not source.is_file() or source.suffix.lower() not in extensions:
        continue

    # 보고서.pdf와 보고서.docx의 결과 이름이 겹치지 않게 합니다.
    target = output_dir / f"{source.name}.md"
    if target.exists():
        print(f"건너뜀: {target.name} (기존 결과 있음)")
        continue

    try:
        result = converter.convert_local(str(source))
        text = result.markdown
        if not text.strip():
            print(f"확인 필요: {source.name} (텍스트 없음)")
            continue
        target.write_text(text, encoding="utf-8")
        print(f"완료: {source.name} -> {target.name}")
    except Exception as error:
        print(f"실패: {source.name} ({type(error).__name__})")

같은 가상환경에서 실행합니다.

python convert_docs.py

이 코드는 convert_docs.py를 저장한 폴더 바로 아래 파일만 처리합니다. 터미널을 연 위치와 스크립트의 위치가 다르면 스크립트의 위치를 기준으로 합니다. 하위 폴더까지 뒤지지 않습니다. 같은 이름의 원본을 수정하고 다시 변환하려면 기존 결과를 다른 곳으로 옮기거나 이름을 바꾼 뒤 실행하세요. 완료 메시지는 변환 실행의 성공을 뜻하며, 표와 수식의 정확성까지 보증하지는 않습니다.

MarkItDown 오류가 나면 무엇부터 확인하나요?

Python 환경 → 파일 경로 → 추출 결과 순서로 확인하면 원인을 좁히기 쉽습니다.

업데이트가 필요한 경우에는 설치했던 가상환경 안에서 실행합니다.

python -m pip install --upgrade "markitdown[all]" markitdown-mcp

업데이트만으로 모든 한글 깨짐이나 표 손실이 해결되지는 않습니다. 원본에서 추출할 수 있는 정보의 품질도 영향을 줍니다.

자주 묻는 질문

오늘은 PDF 한 개만 바꿔 보세요

글자 위주 PDF 한 개를 변환하고, 원본에서 고른 질문에 변환본만으로도 답할 수 있는지 확인해 보세요. 잘 된다면 보고서·회의록처럼 반복해서 읽는 문서에 적용하고, 파일을 자주 옮기는 것이 번거로워질 때 MCP로 확장하면 됩니다.

중요한 것은 파일을 무조건 작게 만드는 일이 아닙니다. 답을 찾는 데 필요한 정보는 남기면서, 필요 없는 입력을 줄이는 것입니다. 그림을 봐야 하는 질문에는 그림을, 본문을 읽으면 되는 질문에는 잘 추출된 텍스트를 전달하세요.

문서 만들기·형식 변환·텍스트 추출 도구를 함께 비교하고 싶다면 OfficeCLI·Pandoc·MarkItDown 문서 자동화 가이드를 이어서 읽어보세요.