“수십 페이지짜리 PDF, 워드, 엑셀 문서를 AI에게 어떻게 읽혀야 할까요? 복잡한 파이썬 가상환경 지옥 없이 클릭 몇 번으로 해결하고 토큰 요금도 획기적으로 아껴보세요!”
가상환경 관리나pip충돌 없이 초고속 파이썬 도구uv를 활용해 마이크로소프트(Microsoft)의 공식 오픈소스 MarkItDown을 설치하고, 오픈코드(OpenCode)와 구글 안티그래비티(Antigravity)에 MCP로 연동하는 방법, 그리고 대형 문서 분석 시 API 토큰 요금을 대폭 절감하는 실전 운영 노하우를 상세히 안내합니다.
안녕하세요. 시니어 회사원의 시선에서 AI 실무 도구를 가장 쉽고 실용적으로 해설하는 블로그의 열아홉 번째 글입니다.
우리가 회사 업무를 하다 보면 보고서, 매뉴얼, 계약서, 논문 등 수많은 문서가 PDF나 워드(Docx), 엑셀(Xlsx) 형식으로 전달됩니다. 앞선 #11편에서는 한국 공문서의 핵심인 아래한글(HWP)을 파싱하는 kordoc MCP를 다루었는데요, 전 세계 표준 문서 포맷인 PDF와 오피스 문서들도 AI가 빠르고 정확하게 읽을 수 있도록 날개를 달아줄 때입니다.
오늘 소개할 도구는 마이크로소프트에서 공개한 강력한 문서 변환 도구 MarkItDown입니다. 특히 복잡한 파이썬 설정 없이 초고속 도구인 uv를 사용하여 깔끔하고 독립적으로 설치하고, 오픈코드 V2에 MCP(Model Context Protocol)로 연동하는 과정을 초보자 눈높이에 맞춰 완벽 정리해 드립니다.
기존 파이썬 환경에서 라이브러리를 설치하다 보면 pip 버전 충돌이나 가상환경(venv/conda) 경로 꼬임으로 고생하는 경우가 많았습니다. 하지만 최신 파이썬 도구인 uv를 이용하면 별도의 가상환경 생성 없이도 전역에서 실행 가능한 도구를 독립된 샌드박스에 즉시 설치할 수 있습니다.
┌────────────────────────────────────────────────────────────────────────┐
│ [ MarkItDown 핵심 강점 ] │
├────────────────────────────────────────────────────────────────────────┤
│ • Microsoft 공식 오픈소스: 신뢰성과 빠른 업데이트 보장 │
│ • 다양한 포맷 원스톱 지원: PDF, Word(.docx), Excel(.xlsx), PPT, HTML │
│ • 깔끔한 마크다운(Markdown) 변환: 표(Table)와 서식을 보존하여 텍스트화 │
│ • 가벼운 구동: 시스템 리소스를 적게 차지하며 대용량 변환에 최적화 │
│ • 공식 MCP 지원: 오픈코드와 구글 안티그래비티 등 AI 에이전트와 즉시 연결│
└────────────────────────────────────────────────────────────────────────┘
| 도구 / 컴포넌트 | 설치 및 구동 방식 | 주요 역할 및 실무 활용도 |
|---|---|---|
| MarkItDown | uv tool install |
PDF, Word, Excel을 마크다운(.md)으로 초고속 변환 (CLI) |
| MarkItDown MCP | opencode mcp add |
오픈코드와 안티그래비티 에이전트가 문서를 직접 읽는 통로 |
| Docling (확장) | uv tool install |
수식, 다단 편집, 복잡한 통계 표가 포함된 고난도 논문/보고서 처리 |
| 오픈코드 / 안티그래비티 | 에이전트 인터페이스 | 변환된 마크다운을 분석·요약하여 질문에 답변 및 코드 생성 |
로컬 캐시 (.pdf-cache) |
디렉토리 저장소 | 중복 변환 방지 및 불필요한 컨텍스트 반복 전송 차단 (토큰 절감) |
uv 환경 점검이미 Mac(iMac/MacBook)이나 PC에서 uv를 사용 중이라면 파이썬을 아주 쉽고 일관되게 관리할 수 있습니다. 먼저 터미널을 열고 버전을 확인합니다.
uv --version
uv python list --only-installed
AI 및 문서 처리 라이브러리들은 최신 파이썬보다는 호환성이 검증된 Python 3.12 환경에서 가장 안정적으로 작동합니다. 만약 설치되어 있지 않다면 한 줄로 설치합니다:
uv python install 3.12
💡 시니어 팁: 불필요한 파이썬 버전 정리
uv python list --only-installed를 실행했을 때/usr/local/Cellar/python@...처럼 Homebrew로 설치된 불필요한 버전이 있다면brew uninstall python@3.15명령어로 깨끗하게 정리할 수 있습니다.
터미널에서 직접 대용량 문서를 마크다운으로 변환할 수 있도록 uv tool로 MarkItDown을 설치합니다.
PDF, 오피스 문서 등 모든 변환 엔진이 포함된 [all] 옵션으로 설치합니다.
uv tool install --python 3.12 "markitdown[all]"
설치가 완료되면 정상 동작하는지 확인합니다:
markitdown --help
만약 command not found: markitdown 메시지가 나타난다면 쉘 경로를 업데이트해 줍니다:
uv tool update-shell
(터미널 창을 닫고 새로 열면 명령어가 정상 인식됩니다.)
가지고 계신 PDF나 워드 파일을 마크다운 파일로 직접 변환해 봅니다:
markitdown ~/Documents/report.pdf -o ~/Documents/report.md
눈 깜짝할 사이에 텍스트와 표가 깔끔한 마크다운(.md)으로 저장되는 것을 확인할 수 있습니다.
이제 오픈코드(OpenCode)나 안티그래비티(Antigravity) 같은 AI 에이전트가 문서를 직접 열어볼 수 있도록 MarkItDown MCP 서버를 준비합니다.
uv tool로 MCP 설치하기uv tool install --python 3.12 markitdown-mcp
설치된 경로를 확인합니다:
which markitdown-mcp
일반적으로 다음과 같은 절대 경로가 출력됩니다:
/Users/사용자명/.local/bin/markitdown-mcp
🔍 참고:
uv tool방식 vsuvx방식
uv tool방식: 내 컴퓨터의 독립 툴 디렉토리에 설치해 두고 지정된 절대 경로(/Users/.../.local/bin/markitdown-mcp)를 안정적으로 호출합니다.uvx방식:uvx markitdown-mcp처럼 사전 설치 없이 즉석에서 가상 환경을 띄워 실행합니다.
두 방식 모두 훌륭하지만, 일상적인 에이전트 작업에서는 경로가 고정된uv tool설치 방식이 프로세스 기동 속도가 빠르고 안정적입니다.
오픈코드 V2(OpenCode 2.x)에서는 터미널 명령어 한 줄로 전역 MCP 서버를 추가할 수 있습니다.
터미널에서 아래 명령을 실행합니다 (which markitdown-mcp로 확인한 경로 입력):
opencode mcp add markitdown --global -- /Users/사용자명/.local/bin/markitdown-mcp
실행 즉시 전역 설정 파일(~/.config/opencode/opencode.json)에 자동 등록됩니다.
opencode.json)~/.config/opencode/opencode.json 파일을 열어보면 OpenCode V2 표준 규격인 mcp.servers 하위에 완벽히 등록된 것을 볼 수 있습니다:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"markitdown": {
"type": "local",
"command": [
"/Users/사용자명/.local/bin/markitdown-mcp"
]
}
}
}
}
(참고: uvx 방식을 사용한다면 command에 ["/Users/사용자명/.local/bin/uvx", "--python", "3.12", "markitdown-mcp"] 형태로 지정할 수도 있습니다.)
터미널에서 등록 상태를 점검합니다:
opencode mcp list
출력 결과에 초록색 체크 표시가 나타나면 준비 완료입니다!
✓ kordoc connected
✓ markitdown connected
이제 오픈코드의 Code Mode 도구 카탈로그에 tools.markitdown.convert_to_markdown이 등록되어, 대화창에서 파일 경로를 주면 AI가 자동으로 마크다운으로 변환해 읽습니다.
일반 업무용 보고서나 문서에는 MarkItDown이 가장 가볍고 빠릅니다. 하지만 다단 배열(2단/3단 컬럼), 복잡하게 병합된 다중 헤더 표, 수식(LaTeX)이 많은 학술 논문이나 기술 표준 문서는 IBM에서 개발한 오픈소스 Docling을 함께 사용하면 좋습니다.
uv tool install --python 3.12 docling
설치 확인 및 변환:
docling --version
docling ~/Documents/paper.pdf --to md --output ~/Documents/converted
직장인들이 AI로 수십~수백 페이지의 PDF 문서를 다룰 때 가장 흔히 하는 실수가 “문서 전체를 통째로 프롬프트에 밀어 넣는 것”입니다.
MCP를 설치했다고 해서 토큰 요금이 저절로 줄어들지는 않습니다. 100페이지짜리 PDF를 한 번 읽을 때마다 수만~수십만 토큰이 소모되고, 질문을 몇 번만 주고받아도 API 요금 폭탄을 맞거나 대화 컨텍스트 한도에 도달하게 됩니다.
다음 5가지 운영 수칙을 꼭 기억하세요!
┌────────────────────────────────────────────────────────────────────────┐
│ [ 대용량 PDF 토큰 절감 5대 수칙 ] │
├────────────────────────────────────────────────────────────────────────┤
│ 1. 1회 변환 후 로컬 캐시(.pdf-cache) 저장: 같은 문서는 재변환하지 않음 │
│ 2. 목차 및 키워드 우선 탐색: 전체 본문 대신 목차(TOC)부터 스캔 │
│ 3. 필요한 섹션만 발췌: 질문과 연관된 특정 장·절·표만 에이전트에 전달 │
│ 4. 출처 페이지 확인: 원본 페이지 번호가 모호하면 추측하지 않도록 지시 │
│ 5. /compact 적극 활용: 세션 대화가 길어지면 슬래시 명령어로 요약 압축 │
└────────────────────────────────────────────────────────────────────────┘
오픈코드나 안티그래비티 대화창에 문서를 의뢰할 때 아래처럼 규칙을 명시해 주면 토큰 낭비를 획기적으로 방지할 수 있습니다:
💬 초보자 추천 토큰 절약 프롬프트:
“첨부한 PDF 문서를 분석할 때 토큰 사용량을 최소화해줘.
1. 먼저markitdown으로 변환하되, 결과를 프로젝트 내.pdf-cache폴더에 저장하고 이미 있다면 재변환하지 마.
2. 문서 전체를 한 번에 다 읽지 말고, 먼저 목차와 핵심 키워드를 스캔해줘.
3. 내 질문과 직접 관련된 문단과 표만 선별해서 읽고 핵심을 요약해줘.
4. 원본 페이지 번호를 확인할 수 없는 정보는 임의로 추측하지 마.”
오늘 우리는 파이썬 환경의 번거로움을 완전히 지워버린 uv와 마이크로소프트의 MarkItDown을 결합하여, 오픈코드(OpenCode)에 강력한 문서 분석 엔진을 장착해 보았습니다.
uv tool install로 가상환경 설정 없이도 MarkItDown과 MarkItDown MCP를 클릭 한 번으로 깔끔하게 설치했습니다.opencode mcp add 명령어로 OpenCode V2 규격에 맞게 전역 MCP 서버로 등록했습니다.kordoc, 일반 PDF와 오피스 문서는 markitdown, 복잡한 학술 논문은 docling이라는 완벽한 3대 문서 처리 라인업이 완성되었습니다.이제 옆자리의 AI 신입사원에게 두꺼운 업무 보고서와 매뉴얼을 건네고, 커피 한잔 마시는 사이에 깔끔하게 정리된 핵심 요약본을 받아보세요!
다음 글에서는 이렇게 구축된 문서 처리 환경을 바탕으로, 실제 대용량 업무 규정집 PDF를 분석하여 사내 Q&A 챗봇 및 검색 도구를 구축하는 실전 응용 편을 다루어 보겠습니다. 많은 기대 부탁드립니다!