PDF 및 Word 파일을 AI용 텍스트로 바꾸는 방법: Microsoft의 MarkItDown

추가 안내는 Ailoot 문서에서 확인할 수 있습니다.

MarkItDown이란 무엇이며, 무엇에 쓰이나요?#

AI에 계약서, 보고서 또는 회계 자료 내보내기 파일을 보내도 문서와 전혀 관계없는 답을 받을 때가 있습니다. 보통 원인은 모델이 아닙니다. 파일 안에는 형식이 있습니다. Word는 마크업이 들어 있는 아카이브이고, Excel은 셀끼리 연결된 스프레드시트이며, PDF는 페이지상의 좌표와 함께 놓인 문자들의 집합입니다. 모델은 텍스트로 작업하므로 누군가 그 텍스트를 추출해야 합니다.

MarkItDown이 바로 그 일을 합니다. 저장소는 github.com/microsoft/markitdown에 있으며 MIT 라이선스가 적용되므로 제한 없이 사용할 수 있습니다. 2026년 8월 18일 기준으로 별 174,412개와 포크 12,756개를 기록했고, 최신 릴리스 0.1.7은 7월 29일에 나왔습니다. 프로젝트는 활발하지만 개발에서 유지보수로 초점이 옮겨졌습니다. 열린 pull request는 481개로, 전체 역사에서 병합된 183개보다 많습니다.

개발자들은 프로젝트의 목적을 다음과 같이 설명합니다.

설명의 다음 문장은 이 도구에 대해 사람들이 제기하는 불만의 절반을 설명합니다.

출력은 모델을 위한 원재료입니다. 보기 좋은 문서는 아니며, 프로젝트는 첫 번째 섹션에서 이를 분명히 밝힙니다.

설명에는 왜 Markdown을 사용하는지도 직접 나옵니다. 주요 모델은 이미 이 마크업을 “말할” 수 있고, 학습 중 엄청난 양을 접했기 때문에 요청하지 않아도 응답에 포함합니다. 마크업은 간결하기도 합니다. 제목 하나에 메타데이터 열두 줄 대신 해시 기호 세 개면 됩니다.

MarkItDown은 일반 변환기와 어떻게 다른가요?#

차이는 예 하나로 분명해집니다. PDF 스무 개가 든 폴더를 pandoc으로 처리해 보세요. 작동하지 않습니다. pandoc은 PDF를 출력할 수는 있지만 입력으로 읽을 수는 없습니다. “문서가 한가득 있는데 모델에 넣어 줘”라는 상황이 가장 흔한데도 말입니다.

MarkItDown 제작자는 어디서든 텍스트만 추출하는 라이브러리인 textract와 자신들을 비교합니다. 차이는 MarkItDown이 제목, 목록, 표, 링크 같은 구조를 보존하려 한다는 점입니다.

실용적인 결론은 간단합니다. 글을 출판용 레이아웃으로 바꿔야 한다면 pandoc을 사용하세요. AI가 계약서 스무 개를 이해하도록 하려면 MarkItDown을 사용하세요.

첫 번째 릴리스가 설치되지 않도록 MarkItDown을 어떻게 설치하나요?#

먼저 올바른 명령어를 살펴보고, 이어서 왜 그 명령어가 올바른지 설명합니다.

1. Python 버전 확인하기

   Python 3.12가 가장 안정적입니다. 테스트한 모든 환경에서 최신 MarkItDown이 설치됩니다. python3 --version 명령어로 현재 버전을 확인할 수 있습니다. Intel Mac이나 구형 macOS를 실행하는 Mac에서는 Python 3.13과 3.14가 조용한 다운그레이드를 일으킬 수 있습니다. Python 3.15는 아래에서 설명하듯 아직 지원되지 않습니다.

2. 형식을 지정해 설치하기

   pip install 'markitdown[pdf,docx,xlsx,pptx]'를 실행하세요. 따옴표가 필요합니다. 그렇지 않으면 셸이 대괄호를 해석합니다. Intel Mac에서는 install 뒤에 --prefer-binary 플래그를 추가하세요.

3. 설치 직후 확인하기

   markitdown --version을 실행하세요. 응답은 markitdown 0.1.8 이상이어야 합니다. 더 낮은 숫자는 설치 과정에서 다운그레이드가 발생했다는 뜻입니다. 이 절에서 그 이유를 설명합니다.

pip install 'markitdown[pdf,docx,xlsx,pptx]'
markitdown --version

프로젝트 설명은 한 번에 전부 설치하는 주 명령어로 pip install 'markitdown[all]'을 제시합니다. 0.1.8이 나온 지 일주일 뒤인 2026년 9월 28일, Apple Silicon Mac에서 Python 3.14.6 및 3.12.12를 사용해 깨끗한 환경 네 곳에서 네 가지 변형을 실행했습니다.

여덟 번의 설치 모두 “Successfully installed”로 끝났고, markitdown --version은 매번 0.1.8을 반환했습니다. 8월에는 최신 릴리스가 0.1.7이었을 때 Python 3.14에서 세 번째 명령어를 실행하면 2025년 3월 8일에 나온 0.0.2가 설치됐습니다. 이는 프로젝트 역사상 두 번째 릴리스입니다. 현재 안정 릴리스는 0.0.1부터 0.1.8까지 열한 개이며, 사전 릴리스를 포함하면 스물여섯 개입니다.

원인은 의존성 체인이었습니다. 0.1.7에서 [all] 추가 항목은 특정 릴리스 계열의 YouTube 자막 라이브러리를 가져오는데, 그 계열의 모든 릴리스는 Python 3.14에서 작동하지 않는다고 선언합니다. 설치 프로그램은 이를 거부하고, 버전이 고정되지 않았기 때문에 설치 가능한 버전을 찾을 때까지 MarkItDown 버전을 하나씩 낮춥니다. 결국 0.0.2를 찾아 설치하면서 1년 반 전의 릴리스가 컴퓨터에 들어갑니다. 0.1.8에서는 자막 라이브러리 요구 버전을 Python 3.14에서 작동하는 계열로 올렸고, 이에 따라 다운그레이드가 멈췄습니다.

이 메커니즘은 여전히 존재합니다. 설치 프로그램이 시스템에 필요한 구성 요소 하나를 찾지 못하면 같은 방식으로 조용히 0.0.2까지 내려갑니다. 최근 버전에서 문제를 일으키는 구성 요소는 파일 형식 감지기에 쓰이는 onnxruntime 엔진입니다. Mac에서는 Python 3.12의 경우 macOS 11 이상, 3.13의 경우 macOS 13, 3.14의 경우 macOS 14 이상을 실행하는 Apple Silicon에서만 빌드됩니다. Mac이 이 요구 사항을 만족하지 않으면 기본 명령어인 pip install markitdown조차 0.0.2를 설치합니다. Rosetta를 통해 Python 3.14를 실행하는 Intel Mac에서 테스트했을 때도 정확히 이런 결과가 나왔습니다. “Successfully installed”, 경고 없음, 설치된 버전은 0.0.2였습니다.

Intel Mac에는 또 다른 문제가 있습니다. 2026년 6월부터 PDF 읽기에 필요한 cryptography 라이브러리는 이 프로세서용 사전 빌드 버전 없이 배포됩니다. 그래서 설치 프로그램은 소스에서 빌드하려고 합니다. 명령어에 --prefer-binary 플래그를 추가하면 사전 빌드 패키지가 있는 이전 버전을 사용합니다. Intel의 Python 3.13에서 테스트했을 때 0.1.8이 설치됐고 PDF도 열렸습니다. 이 플래그는 알려진 취약점 세 개가 있는 cryptography 48.0.1을 설치합니다. 취약점은 PKCS#7 복호화와 인증서 체인 검증에 있습니다. MarkItDown은 암호화된 PDF를 복호화할 때만 이 기능을 사용하며, 문서 읽기에서는 해당 부분에 접근하지 않습니다.

Python 3.15에서는 두 가지 이유로 다운그레이드가 발생합니다. 버전 0.1.8은 3.10부터 3.14까지만 지원한다고 선언하며, 3.15용 엔진도 아직 없습니다. Python 3.15에서 설치 프로그램의 의존성 해결 결과가 이를 확인해 줍니다. 기본 명령어와 형식을 지정한 명령어 모두 똑같이 0.0.2를 설치합니다.

다운그레이드 경고는 다음과 같이 표시되며, 명령어에 포함된 각 추가 항목마다 한 줄씩 나옵니다.

WARNING: markitdown 0.0.2 does not provide the extra 'all'

이 줄은 다운로드 메시지 수십 개 사이에 묻히며 대체된 버전에 대해서는 아무것도 알려 주지 않습니다. 추가 항목 없는 기본 명령어를 사용하면 경고조차 없습니다. 마지막에는 “Successfully installed”라는 반가운 메시지만 나옵니다.

추가 항목 없이 설치하는 것도 해결책이 아닙니다. 기본 패키지는 설치되지만 PDF를 열 수 없습니다.

PdfConverter recognized the input as a potential .pdf file, but the
dependencies needed to read .pdf files have not been installed. To resolve
this error, include the optional dependency [pdf] or [all] when installing
MarkItDown. For example:

* pip install 'markitdown[pdf]'
* pip install 'markitdown[all]'

도구 자체는 [all]을 권장하며, 0.1.8에서는 이 권장 사항이 Python 3.14와 3.12에서 다시 작동합니다. 그래도 형식을 이름으로 지정하는 편이 낫습니다. [all]은 패키지 열다섯 개가량과 약 55메가바이트를 추가합니다. 여기에는 사전 릴리스 Azure 라이브러리와 이미 한 번 설치를 실패하게 한 바로 그 YouTube 의존성 체인도 포함됩니다.

설치 프로그램은 Azure 사전 릴리스를 알아서 처리합니다. 보통 pip는 사전 릴리스를 건너뛰지만, 이 경우 요구 사항에 사전 릴리스가 명시되어 있으므로 설치합니다. Python 3.12에서 pip 버전 23.2부터 26.2까지 네 가지를 테스트했으며, 모두 0.1.8을 선택했습니다.

8월에 다른 깨끗한 환경에서 다시 설치했을 때도 같은 결과가 나왔습니다. 0.0.2와 “Successfully”라는 단어였습니다.

미리 알아 두면 좋은 실용적인 세부 사항이 몇 가지 있습니다.

크기가 꽤 큽니다. 기본 설치는 143메가바이트, 형식 네 가지를 포함하면 303메가바이트입니다. 가장 무거운 구성 요소는 81메가바이트인 파일 형식 감지기이며, 기본 설치에까지 포함됩니다. 노트북에서는 문제가 되지 않지만 크기 제한이 있는 클라우드 함수에는 문제가 됩니다.

미러를 대안으로 기대하지 마세요. 테스트한 미러에는 인덱스와 MarkItDown 파일이 있었지만 필수 의존성 하나가 빠져 있어 Python 3.14와 3.12 모두 설치가 실패했습니다.

설치는 핵심 문제에 비하면 사소합니다. AI가 엉뚱한 결과를 내는 훨씬 흔한 이유는 잘못된 대상이나 그 대상의 잘못된 표현이 컨텍스트 창에 들어가기 때문입니다. 작업을 맡기기 전에 모델에 무엇을 제공할지 결정하는 역량을 context engineering이라고 하며, 문서 준비도 그 일부입니다.

첫 번째 문서를 텍스트로 바꾸려면 어떻게 하나요?#

가장 간단한 방법은 다음과 같습니다.

markitdown dogovor.docx

텍스트가 터미널에 출력됩니다. 파일로 저장하는 방법은 두 가지입니다.

markitdown dogovor.docx -o dogovor.md
markitdown dogovor.docx > dogovor.md

Mac과 Linux에서는 차이가 거의 없지만 Windows에서는 중요합니다. 출력에 키릴 문자가 있으면 >를 통한 리디렉션으로 프로그램이 충돌할 수 있습니다.

파일을 스트림으로 전달할 수도 있습니다. 이 경우 확장자를 알려 주면 유용합니다.

cat dogovor.docx | markitdown -x docx

다음은 버전 0.1.8 도움말에 나온 주요 플래그입니다.

같은 도움말에는 유용한 플래그 세 개가 더 나와 있으며, 모두 테스트했습니다. --list-plugins는 설치된 플러그인을 표시하고, -p는 특정 실행에서 플러그인을 활성화하며, --keep-data-uris는 문서에 포함된 이미지를 출력에 유지합니다. 기본값은 이미지를 자르는 것입니다. 나머지는 Microsoft 클라우드 서비스 설정입니다.

Python 래퍼는 세 줄입니다.

from markitdown import MarkItDown

md = MarkItDown()
print(md.convert("ostatki.xlsx").text_content)

같은 호출에 URL도 전달할 수 있습니다. 간단한 페이지에서는 메뉴와 바닥글 없이 제목과 링크를 포함한 167자 분량의 깔끔한 텍스트가 반환됐습니다.

r = md.convert("https://example.com")

MarkItDown은 어떤 형식을 이해하며, 실제로는 무엇을 뜻하나요?#

주장하는 내용과 실제 동작을 요약한 표입니다.

세 가지 항목을 자세히 살펴보겠습니다.

이미지. 설명에 OCR이라는 단어가 들어 있어 사진 속 텍스트를 읽을 거라고 기대하는 사람이 있습니다. 하지만 그렇지 않습니다. 별도 프로그램인 exiftool을 사용해 메타데이터를 읽습니다. 또한 직접 준비한 키로 비전 모델을 연결하면 설명을 위해 이미지 자체를 보낼 수 있습니다.

오디오. 음성 받아쓰기는 가능하지만 언어 정보가 전달되지 않으며 엔진은 기본적으로 영어를 예상합니다. 또한 키당 하루 약 50회로 제한된 Google의 비공식 무료 엔드포인트를 호출합니다.

아카이브. 프로그램은 ZIP 파일의 압축을 풀고 내부 파일을 순회하면서 결과를 이어 붙입니다. 파일을 분석하지 못하면 오류가 잡혀서 무시됩니다. 파일은 결과에 나타나지 않으며, 사용자는 그 사실을 알 수 없습니다.

키릴 문자가 포함된 문서는 어떻게 되나요?#

아래 파일은 테스트용으로 특별히 만들었으며, 데이터는 임의로 구성했습니다.

Excel 재고표도 깔끔하게 변환됐고, 시트 이름은 제목으로 바뀌었습니다.

## Stock
| Item | In stock | Reserved | Available |
| --- | --- | --- | --- |
| Coffee beans, kg | 420 | 38 | 382 |
| Loose-leaf tea, kg | 180 | 52 | 128 |

프레젠테이션은 텍스트로 바뀌었습니다. 슬라이드 번호는 주석으로 표시되고 슬라이드 제목은 제목으로 변환됐습니다. 여기서도 키릴 문자 텍스트는 온전합니다. “MarkItDown은 키릴 문자를 이해하지 못한다”라는 포괄적인 주장은 사실이 아닙니다.

이제 문제가 발생하는 세 곳을 살펴보겠습니다.

세미콜론으로 구분된 CSV. 비교를 위해 동일한 청구서 내보내기 파일 두 개를 처리했습니다. 쉼표를 사용한 파일은 올바른 네 열 표를 만들었습니다. 세미콜론을 사용하면 행 전체가 하나의 셀에 들어갑니다.

행 전체가 한 셀에 들어갔습니다. 인코딩은 제대로 인식됐고 오류도 없었습니다. -c 플래그도 도움이 되지 않습니다. 모델은 이 표를 받더라도 어떤 값이 금액이고 어떤 값이 상태인지 이해하지 못할 것입니다. 원본을 유지하고 쉼표 구분자와 올바른 인코딩을 명시해 다시 내보내세요. 따옴표 안의 구분자와 소수점 쉼표는 값의 일부일 수 있으므로 세미콜론을 일괄 치환하지 마세요. 다시 내보낼 수 없다면 실제 구분자로 원본을 파싱하고 따옴표 및 셀 값을 보존하는 CSV 전용 쓰기 도구로 새 파일을 만드세요. 분석 전에 원본과 열 수, 행 수, 검증용 합계를 비교하세요.

Excel 통화 서식. 통화 기호는 셀의 표시 설정에 저장되어 있으며 값 자체에는 포함되지 않습니다. 프로젝트 관리자들이 원인을 확인했습니다. 가격표나 청구서에서는 중요한 문제입니다. 모델은 숫자를 보면서도 어떤 통화인지 알 수 없습니다.

Windows 콘솔. 라틴 문자가 아닌 문자가 포함된 파일에서는 프로그램이 충돌할 수 있습니다.

오류 추적에는 Windows 콘솔을 뜻하는 cp1251 인코딩이 표시됩니다. 문서 자체는 제대로 분석되지만 터미널 창에 결과를 출력하는 과정에서 실패합니다. 해결 방법은 두 가지입니다.

markitdown dogovor.docx -o dogovor.md
$env:PYTHONUTF8 = "1"; markitdown dogovor.docx > dogovor.md

첫 번째 방법은 콘솔을 완전히 우회하고, 두 번째는 Python이 UTF-8로 쓰도록 합니다. 도구 자체에서 이 문제를 수정하려는 제안이 최소 여섯 번 제출됐습니다. 일부 제안은 병합되지 않은 채 종료됐고 나머지는 아직 열려 있습니다. 따라서 우회 방법을 사용해야 합니다.

네 번째 증상은 PDF에서 나타납니다. 글자 대신 (cid:1090) 같은 문자열이 보입니다. 파일의 폰트 표가 표준이 아니어서 문자를 해독하지 못했다는 뜻입니다. 이런 문서를 MarkItDown으로 처리해도 소용없습니다. 다른 도구가 필요합니다.

PDF가 왜 엉망으로 나오나요?#

테스트에서는 크기 2.16메가바이트의 2단 과학 논문을 처리했습니다. 종료 코드는 0이었습니다. 0.9초 뒤 출력에는 88,000자가 들어 있었고 거의 전부 엉망이었습니다. 문자 88,000개만 보면 모두 잘된 것처럼 보입니다. 파일을 열어 보기 전까지는요.

|     | Hybrid |          | OCR-LLM     |     | Framework  |
| --- | ------ | -------- | ----------- | --- | ---------- |
...
Informationextractionfromcopy-heavydoc-
5202 tcO 11  ]LC.sc[  1v83101.0152:viXra

세 가지 문제가 동시에 발생했습니다. 2단 레이아웃이 논문에 없던 표로 바뀌었습니다. 단어 사이 공백이 사라졌습니다. 마지막 줄은 페이지의 세로 사이드바가 거꾸로 추출된 것입니다.

그다음에는 우스운 일이 벌어졌습니다. 테스트 논문은 MarkItDown을 측정하고 다른 도구와 비교한 바로 그 연구였습니다. 도구는 자체 측정 결과를 보고하는 문단을 다음처럼 바꿨습니다.

cues. This name-matching error could be miti-  OCRpreprocessingoverhead(0.056s),whileDo-
gatedthroughpromptengineeringtoprovidemore  clingandMinerUadoptmorecomputationallyin-
explicit matching instructions or fine-tuning the  tensive strategies with OCR latencies of approxi-

왼쪽 열과 오른쪽 열이 줄마다 이어집니다. 모델에 이 결과를 주면 한 문단의 문장 절반과 다른 문단의 절반을 읽게 됩니다.

원인은 기술적으로 간단합니다. Word는 “이것은 제목이다”, “이것은 표 셀이다”라고 명시적으로 저장합니다. PDF는 “이것은 문자다”, “이것은 페이지 위의 좌표다”라고 저장합니다. 좌표에서 구조를 재구성하는 것은 별도의 어려운 작업이며, MarkItDown은 거의 시도하지 않습니다. PDF 분석 소스 코드에는 제목 탐지 기능이 없습니다. 페이지가 양식이나 표로 인식되지 않으면 문서 전체가 기본 텍스트 추출을 거칩니다.

사용자들은 과학 논문과 표를 포함해 이 문제를 프로젝트 저장소에 자주 보고합니다.

소스 코드에서 확인되듯 도구는 PDF에서 제목을 단 하나도 찾지 못합니다.

“MarkItDown의 정확도는 82%”라는 수치가 방법론 없이 온라인에 퍼져 있습니다. 원출처를 추적해도 찾을 수 없습니다. 링크를 따라가면 끝에 로드되지 않는 페이지가 나옵니다. 측정 결과로 취급할 수 없습니다.

스캔한 계약서는 어떻게 되나요?#

이 동작은 실패처럼 보이지 않기 때문에 다른 문제보다 위험합니다.

테스트를 위해 텍스트가 있는 이미지에서 PDF를 만들었습니다. 계약서를 촬영하거나 스캔하면 정확히 이런 결과가 나옵니다. 우연이 아닌지 확인하려고 실행을 반복했습니다.

문자도 오류도 0이며 두 번 연속으로 같은 결과가 나왔습니다. 종료 코드 0은 “모든 것이 잘됐다”라는 뜻입니다. 종료 코드로 성공 여부를 확인하는 스크립트라면 문서가 처리된 것으로 간주합니다. 그런 다음 빈 출력이 모델에 전달되고, 모델은 아무것도 보지 못한 채 허공에서 답을 지어내기 시작합니다.

해결 방법은 두 가지이며 모두 유료입니다. 첫 번째는 -d 플래그입니다. 문서를 Microsoft의 클라우드 인식 서비스로 전송하며, 플래그 도움말에는 유효한 서비스 엔드포인트가 필요하다고 명시되어 있습니다. 두 번째는 페이지를 사용자 키로 비전 모델에 보내는 별도 추가 패키지로, 페이지마다 모델 제공업체에 비용을 내야 합니다. 2026년 4월부터 열린 토론에서는 두 번째 방법이 여러 페이지로 된 스캔에서 첫 페이지만 처리한다는 보고가 나왔습니다.

자체 컴퓨터에서 인식 모델을 실행할 수도 있지만, 별도의 프로젝트입니다.

문서 한 건만 처리한다면 파일을 열고 텍스트를 직접 복사하는 편이 쉽습니다. 스캔을 계속 처리해야 한다면 인식 기능이 내장된 도구가 필요합니다.

온라인 변환기에 파일을 올려도 되나요?#

“MarkItDown online”은 검색에서 가장 흔히 제안되는 문구 중 하나이며, 이를 제공한다는 사이트도 있습니다. Microsoft의 원래 도구에는 웹사이트가 없습니다. 직접 설치하는 프로그램으로만 제공됩니다. 비슷한 이름으로 브라우저에서 열리는 것은 무엇이든 다른 사람이 만든 것입니다.

1분이면 이런 서비스를 확인할 수 있습니다. 개발자 도구의 네트워크 요청 탭을 열고, 무해한 파일을 하나 업로드한 다음 서버로 전송되는지 확인하세요. 전송된다면 브라우저에서 처리한다는 주장은 FAQ가 아무리 자신 있게 말해도 거짓입니다.

문서를 조직 밖으로 보낼 수 없는 환경에서 MarkItDown이 높은 평가를 받는 이유입니다. 한 토론에서 누군가는 업무용 노트북에 임의의 프로그램을 설치하는 것은 금지됐지만 Python 라이브러리는 허용됐고, 결국 이 로컬 유틸리티가 유일하게 쓸 수 있는 선택지였다고 설명했습니다.

MarkItDown은 실제로 얼마나 절약해 주나요?#

Office 파일은 마크업을 담은 아카이브 구조입니다. 테스트 파일 세 개를 압축 해제하고 콘텐츠 부분의 크기와 출력 크기를 비교하면 다음과 같습니다.

파일이 작으므로 큰 파일에서는 비율이 달라질 수 있고, 절감량을 하나의 숫자로 말할 수는 없습니다. 비교 글에 반올림한 수치가 나오면 방법론을 물어보세요.

개발자들도 절감 효과를 언급합니다. 프로젝트 설명은 Markdown 규칙이 문자 수 측면에서 매우 경제적이라고 명시합니다. 맞는 말이지만 이를 주요 판매 포인트로 삼아서는 안 됩니다. “모델에 15,000자 대신 3,000자를 제공했다”와 “모델에 뒤죽박죽 대신 명확한 구조를 제공했다”는 차원의 문제입니다. 전자는 비용을 줄이고, 후자는 답변이 말이 되는지를 결정합니다.

컨텍스트 사용량이 걱정된다면 별도 문서인 Claude에서 토큰이 사용되는 곳과 각 요금제에 포함된 토큰 수를 참고하세요.

Claude Code MCP 설정: MarkItDown에 연결하려면 어떻게 하나요?#

MCP는 AI가 스스로 사용할 수 있는 외부 도구를 제공하는 방식입니다. 작동 방식과 다른 서버를 살펴보려면 Claude Code용 MCP 서버 리뷰를 참고하세요.

MarkItDown 서버는 도구 하나만 제공합니다. 문서를 텍스트로 변환합니다. 로컬 파일 경로, 웹페이지 URL 또는 요청에 직접 포함된 데이터를 받을 수 있습니다.

서버 버전을 고정해 명령어 하나로 Claude Code에 연결할 수 있습니다. uv 패키지 관리자가 필요합니다.

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초에서 1.5초 사이에 시작됩니다.

다음은 직접 확인한 제한 사항입니다.

빌드 0.0.1a7은 2026년 9월 14일에 출시됐습니다. 그전까지 서버는 2025년 5월 버전 0.0.1a4에 1년 넘게 머물러 있었습니다. 최신 버전 번호도 여전히 사전 릴리스입니다.

최신 버전의 Python을 사용하는 모든 시스템에 설치되는 것은 아닙니다. 의존성인 onnxruntime 엔진은 Python 3.14에서 macOS 14 이상을 실행하는 Apple Silicon Mac에만 제공됩니다. 따라서 Intel Mac과 macOS 13 이하에서 Python 3.14를 사용하는 경우 설치에 실패합니다. Apple Silicon Mac에서는 Python 3.14, 3.13, 3.12로 서버를 실행했으며 세 버전 모두 설치됐습니다. 명령어에서 UV_PYTHON=3.12를 사용하는 이유는 Windows, Linux, Apple Silicon Mac용 Python 3.12 사전 빌드 패키지가 제공되고, 해당 버전이 없으면 uv가 내려받기 때문입니다. Intel Mac에는 여기에도 제약이 있습니다. 2026년 6월 이후 Intel용 사전 빌드 패키지가 없어서 uv가 cryptography 라이브러리를 소스에서 빌드해야 합니다. 설치 시간이 길어지고 실패할 수 있습니다.

내부에 설치되는 MarkItDown 버전은 uv 버전에 따라 달라집니다. MarkItDown 0.1.6부터 [all] 추가 항목은 Azure 사전 릴리스 라이브러리를 요구합니다. uv 0.12 이상은 이 라이브러리와 최신 MarkItDown 0.1.8을 설치하지만, 이전 uv 버전은 0.1.5로 다운그레이드합니다. uv --version으로 uv 버전을 확인하세요.

두 가지가 컴퓨터 밖으로 전송됩니다. 첫 번째는 원격 측정 데이터입니다. Mac과 Linux에서는 서버 내부의 onnxruntime 엔진이 기본적으로 Microsoft에 데이터를 보냅니다. 명령어의 ORT_DISABLE_TELEMETRY=1 변수가 이를 끕니다. 테스트에서는 이 변수가 없을 때 서버가 Microsoft 원격 측정 엔드포인트에 연결됐습니다. 변수를 설정한 뒤 디스크의 파일을 처리하는 동안에는 연결이 전혀 없었습니다.

두 번째는 오디오입니다. 서버는 WAV, MP3, M4A, MP4 파일을 일반 HTTP를 통해 암호화 없이 Google 음성 인식 서비스로 보내 받아쓰기를 수행합니다. 고객과의 대화를 녹음한 파일은 보내지 않는 편이 좋습니다.

큰 문서는 처리되지 않습니다. 열린 토론에는 서버 응답 51,000토큰이 25,000토큰 제한에 걸린 사례가 설명되어 있습니다. 도구는 파일을 여러 조각으로 나누지 않습니다.

보안 문제도 있습니다. 패키지 자체 문서에는 다음과 같이 명시되어 있습니다.

즉 이 도구를 가진 에이전트는 사용자가 읽을 수 있는 모든 것을 읽을 수 있습니다. 자기 컴퓨터에서 작업할 때는 괜찮습니다. 서버를 공개적으로 노출하거나 신뢰할 수 없는 에이전트에 제공해서는 안 됩니다.

일반적인 작업에서는 명령어로 프로그램을 실행하고 결과 텍스트를 프로젝트에 넣는 편이 쉽습니다. 그러면 파일은 다른 자료와 함께 놓이고, 모델이 알아서 참고할 수 있습니다.

언제 다른 도구를 쓰는 편이 더 솔직한 선택인가요?#

작업을 기준으로 비교해 봅시다. GitHub 별 수와는 관계없습니다.

비교 글이 흔히 빠뜨리는 Marker의 세부 사항이 있습니다. 2026년 7월부터 코드 자체에는 허용적 라이선스가 적용됐지만 모델 가중치에는 별도의 기준이 있는 라이선스가 적용됩니다. 전년도에 회사 매출이 500만 달러를 넘지 않고 조달한 자금도 같은 금액을 넘지 않았다면 무료로 사용할 수 있습니다. 경쟁 제품을 만드는 사람이 사용하는 것도 별도 조항으로 금지합니다. 대부분의 독자에게는 해당하지 않지만, 성장 중인 기업이라면 도입 전에 라이선스를 읽어 볼 이유가 됩니다.

여기서 실용적인 4단계 작업 흐름을 도출할 수 있습니다.

1. 모든 파일을 MarkItDown으로 처리합니다. 무료이고 즉시 끝납니다.
2. 결과를 열어 크기를 확인합니다.
3. 텍스트가 말이 되면 작업이 끝난 것입니다. 다른 작업은 필요 없습니다.
4. 출력이 엉망이거나 비어 있다면 해당 파일만 더 강력한 도구로 처리합니다.

그러면 그런 처리가 필요한 문서에만 시간과 복잡성 비용을 들이면 됩니다.

MarkItDown을 작업 흐름에 어떻게 넣을 수 있나요?#

Anthropic은 Office 파일 작업용 사전 제작 skill에서 MarkItDown을 사용합니다. 해당 skill에는 따라야 할 경계가 명확히 적혀 있습니다.

텍스트에서는 셀과 페이지 참조가 사라지므로 이를 사용해 원본 파일을 변경할 수 없습니다. 세 가지 상황을 살펴보겠습니다.

비슷한 문서 묶음: 확인서, 청구서, 양식, 신청서. 폴더에 모은 다음 한 줄로 처리하세요.

for f in dokumenty/*.docx; do markitdown "$f" -o "text/$(basename "$f" .docx).md"; done

그런 다음 텍스트 파일 폴더를 모델에 제공하고 필요한 정보를 표로 정리해 달라고 요청하세요. 디지털 파일에는 잘 작동합니다. 스캔은 실패하며 크기가 0인 것을 보면 바로 알아챌 수 있습니다.

가격표, 계약서 템플릿, 정책, 서비스 설명 등 프로젝트의 상시 참고 자료. 한 번 텍스트로 변환해 프로젝트 옆에 둡니다. 그러면 모델이 요청할 때마다 읽을 수 있어 대화에 파일을 매번 첨부할 필요가 없습니다. Claude에 파일 업로드하기 문서에서는 이를 채팅에 파일을 업로드하는 것과 비교해 설명합니다.

회계 시스템 내보내기 파일. 회계 소프트웨어나 은행 계좌의 Excel 내보내기 파일은 3분의 1초 만에 표로 바뀌며, 모델은 별도 작업 없이 계산할 수 있습니다. CSV의 실제 구분자, 따옴표 규칙, 인코딩으로 내보내거나 파싱했는지 확인하고 모델에 주기 전에 행, 열, 검증용 합계를 비교하세요. 검색·바꾸기로 구분자를 정규화하지 마세요. Excel 셀 서식에만 있는 통화 기호는 추출 시 사라지므로 통화도 명시적으로 기록하세요.

터미널에서 대용량 PDF를 처리하는 것은 이 목록에 없습니다. 컨텍스트 사용량과 관련된 별도 문제이며 토큰을 잃지 않고 Claude Code에서 PDF 사용하기 문서에서 다룹니다. 작업 환경을 막 설정하는 중이라면 Claude Code 설치하기부터 시작하세요.

바로 시작하려면 pip install 'markitdown[pdf,docx,xlsx,pptx]'를 실행하고, 처음 발견한 Word 계약서를 처리한 다음 결과 크기를 확인하세요. 30초면 자신의 파일에서 작동하는지 알 수 있습니다.

준비가 되면 Ailoot을 만나 보세요.