본문 바로가기
  • AI 시대에 적응하는 현대인을 위한 지식 공간
  • AI를 위한 데이터를 과학으로 역어본다
AI 코딩

MarkItDown으로 모든 문서를 마크다운으로 변환하기

by 피크나인 2026. 4. 20.

MarkItDown 완벽 가이드  |  Microsoft의 문서-마크다운 변환 도구로 LLM 파이프라인 구축하기

PDF, Word, Excel부터 이미지, 오디오까지, AI가 읽을 수 있는 마크다운으로 한 번에 변환하는 방법을 소개합니다. 기업의 디지털 전환이 가속화되면서 수많은 문서가 다양한 형식으로 쏟아지고 있습니다. 그런데 이 문서들을 AI에게 읽히려면 어떻게 해야 할까요? PDF를 그대로 GPT-4o에 넣으면 원하는 결과를 얻기 어렵고, PowerPoint 슬라이드를 Claude에게 분석시키려면 텍스트를 일일이 복사해야 합니다.

 

Microsoft가 이 문제를 해결하기 위해 만든 오픈소스 도구가 바로 MarkItDown입니다. 이 글에서는 MarkItDown의 개념부터 설치, CLI 활용, LLM 통합, 그리고 Local LLM과의 연동까지 실전에서 바로 쓸 수 있는 내용을 단계별로 안내해 드리겠습니다.

MarkItDown은 다양한 문서 형식을 AI가 이해할 수 있는 마크다운으로 변환하는 통합 파이프라인입니다
MarkItDown은 다양한 문서 형식을 AI가 이해할 수 있는 마크다운으로 변환하는 통합 파이프라인입니다

목 차

1. MarkItDown이란 무엇인가?

MarkItDown은 Microsoft Research의 AutoGen 팀이 개발한 오픈소스 Python 유틸리티입니다. 이 도구의 핵심 목적은 PDF, Word, Excel, PowerPoint, 이미지, 오디오 등 다양한 파일 형식을 LLM(Large Language Model, 대규모 언어 모델)이 바로 처리할 수 있는 마크다운(Markdown) 형식으로 변환하는 것입니다. 단순한 텍스트 추출기가 아니라, 제목, 목록, 표, 링크 같은 문서의 구조를 마크다운 문법으로 충실히 보존하는 데 초점을 맞추고 있습니다. MIT 라이선스로 배포되어 상업적 프로젝트에서도 자유롭게 사용할 수 있으며, 2024년 말 공개 이후 폭발적인 관심을 받아 2026년 4월 현재 GitHub 스타 87,000개 이상, Fork 5,100개 이상을 기록하고 있습니다.

 

MarkItDown이 탄생하게 된 배경에는 AutoGen 프로젝트가 있습니다. AutoGen은 Microsoft가 개발한 오픈소스 멀티 에이전트 프레임워크로, 여러 AI 에이전트가 협력하여 복잡한 작업을 수행하는 시스템입니다. AutoGen 팀은 GAIA 벤치마크(범용 AI 어시스턴트 평가 표준)에서 AI 에이전트가 Word 파일, PowerPoint 발표 자료, Excel 스프레드시트, PDF 보고서 등 다양한 형식의 문서를 읽고 이해해야 하는 과제에 직면했습니다. 이때 "어떻게 하면 AI 에이전트가 모든 종류의 문서를 빠르고 정확하게 읽을 수 있을까?"라는 질문에서 MarkItDown이 만들어지게 되었습니다. 즉, MarkItDown은 처음부터 AI를 위한 문서 변환기로 설계된 도구입니다.

 

기존에도 textract라는 유사한 Python 라이브러리가 있었지만, MarkItDown은 몇 가지 핵심적인 차이점을 가지고 있습니다. textract가 다양한 파일에서 순수 텍스트(plain text)를 추출하는 데 초점을 맞춘 반면, MarkItDown은 문서 구조를 마크다운으로 보존하는 것을 우선시합니다. 예를 들어, Word 문서의 제목은 마크다운의 # 헤딩으로, 표는 마크다운 테이블로, 링크는 마크다운 링크 문법으로 변환됩니다. 이렇게 구조가 보존된 마크다운은 LLM이 문서의 맥락과 계층 관계를 훨씬 잘 이해할 수 있게 해줍니다. 또한 MarkItDown은 플러그인 시스템을 지원하여 커뮤니티가 새로운 파일 형식이나 기능을 자유롭게 추가할 수 있도록 설계되었습니다.

[i] 참고: MarkItDown은 이름이 Markdown과 비슷하지만, Markdown 언어 자체와는 별개의 독립적인 소프트웨어입니다. Markdown을 "출력 형식"으로 사용하는 "파일 변환 도구"로 이해하시면 됩니다.

2. 왜 마크다운인가?  |   LLM 시대의 문서 표준

마크다운(Markdown)은 일반 텍스트(plain text)에 매우 가까우면서도, 문서의 구조를 표현할 수 있는 최소한의 마크업을 제공하는 경량 문서 형식입니다. #으로 제목을, -로 목록을, |로 표를 표현하는 단순한 문법 덕분에 사람이 읽기에도 편하고, 기계가 파싱하기에도 효율적입니다. 그런데 이 단순한 형식이 왜 LLM 시대에 "문서 표준"이라고 할 수 있을 만큼 중요한 위치를 차지하게 되었을까요? 그 이유는 현대 LLM의 학습 데이터와 밀접하게 관련되어 있습니다.

 

OpenAI의 GPT-4o, Anthropic의 Claude, Google의 Gemini 같은 주류 LLM들은 방대한 양의 마크다운 형식 텍스트로 학습되었습니다. GitHub의 README 파일, 기술 문서 사이트, 위키 페이지 등 인터넷에 존재하는 수많은 마크다운 콘텐츠가 학습 데이터에 포함되어 있기 때문입니다. 그 결과, 이 모델들은 마크다운을 일종의 "네이티브 언어"처럼 이해하고 생성합니다. 실제로 ChatGPT나 Claude에게 질문을 하면, 별도의 지시 없이도 응답에 마크다운 문법(볼드, 코드 블록, 목록 등)을 자연스럽게 사용하는 것을 볼 수 있습니다. 이는 LLM이 마크다운의 구조적 의미를 깊이 이해하고 있다는 증거입니다.

 

반면, PDF나 DOCX, PPTX 같은 바이너리 파일 형식은 LLM이 직접 처리하기에 근본적인 한계가 있습니다. PDF는 본질적으로 "인쇄 레이아웃"을 기술하는 형식이지 "문서 구조"를 기술하는 형식이 아닙니다. 같은 내용이라도 PDF에서는 텍스트의 x, y 좌표와 폰트 정보로 저장되어 있어, 어디가 제목이고 어디가 본문인지를 기계적으로 판단하기 어렵습니다. DOCX나 PPTX는 XML 기반이긴 하지만, 복잡한 스타일 정보와 메타데이터가 뒤섞여 있어 LLM에게 전달하면 토큰을 불필요하게 낭비하게 됩니다. 마크다운은 이런 "소음(noise)"을 제거하고 핵심 구조와 내용만 남기기 때문에, 동일한 정보를 훨씬 적은 토큰으로 표현할 수 있습니다.

 

토큰 효율성은 LLM 활용에서 실질적인 비용 차이로 이어집니다. 예를 들어, 동일한 내용의 HTML 문서를 마크다운으로 변환하면 토큰 수가 상당히 줄어듭니다. HTML에서는 <h1>, <p>, <table>, <tr>, <td> 같은 태그가 모두 토큰으로 계산되지만, 마크다운에서는 #, -, | 같은 최소한의 기호만 사용되기 때문입니다. 이는 특히 RAG(Retrieval-Augmented Generation, 검색 증강 생성) 파이프라인에서 중요합니다. RAG에서는 대량의 문서를 벡터 데이터베이스에 저장하고 검색한 뒤 LLM에 전달하는데, 이때 마크다운으로 전처리된 문서는 청킹(chunking, 문서를 적절한 크기로 분할하는 작업)이 용이하고, 각 청크가 구조적 의미를 유지하므로 검색 품질이 향상됩니다.

flowchart LR
    subgraph 입력["다양한 문서 형식"]
        PDF["PDF"]
        DOCX["DOCX"]
        PPTX["PPTX"]
        XLSX["XLSX"]
        HTML["HTML"]
        IMG["이미지"]
    end

    subgraph 변환["MarkItDown 변환"]
        ENGINE["변환 엔진"]
    end

    subgraph 출력["마크다운 출력"]
        MD["구조화된 .md"]
    end

    subgraph 활용["LLM 파이프라인"]
        CHUNK["청킹"]
        EMBED["임베딩"]
        VECDB["벡터 DB"]
        LLM["LLM 추론"]
    end

    PDF --> ENGINE
    DOCX --> ENGINE
    PPTX --> ENGINE
    XLSX --> ENGINE
    HTML --> ENGINE
    IMG --> ENGINE
    ENGINE --> MD
    MD --> CHUNK --> EMBED --> VECDB --> LLM

    style ENGINE fill:#4A90D9,stroke:#333,color:#fff
    style MD fill:#2ECC71,stroke:#333,color:#fff

3. MarkItDown의 핵심 가치와 성능  |  AI 협업의 관점에서

지원 파일 형식

MarkItDown의 가장 큰 강점 중 하나는 하나의 도구로 매우 다양한 파일 형식을 처리할 수 있다는 점입니다. 각 파일 형식마다 내부적으로 최적화된 파서(parser, 파일을 분석하는 엔진)를 사용하며, 단일 인터페이스(convert() 메서드 또는 markitdown CLI)로 모든 형식을 동일하게 변환할 수 있습니다.

 

아래 표는 현재 지원되는 파일 형식과 각각의 내부 처리 엔진을 정리한 것입니다.

분류 파일형식 내부처리엔진 설명
Office 문서 DOCX (Word) mammoth Word 문서의 제목, 본문, 표, 이미지 링크를 마크다운으로 변환합니다. 서식 정보는 구조적 의미만 보존됩니다
Office 문서 PPTX (PowerPoint) python-pptx 슬라이드를 위에서 아래, 왼쪽에서 오른쪽 순서로 읽어 텍스트와 구조를 추출합니다. 그룹화된 도형도 지원합니다
Office 문서 XLSX (Excel) pandas 스프레드시트의 각 시트를 마크다운 테이블로 변환합니다. 수식 결과값이 추출됩니다
Office 문서 XLS (구형 Excel) pandas 이전 형식의 Excel 파일도 동일한 방식으로 처리합니다
문서 PDF pdfminer.six 텍스트 기반 PDF에서 텍스트와 기본 구조를 추출합니다. 스캔된 PDF는 별도 OCR이 필요합니다
웹/텍스트 HTML beautifulsoup4 웹 페이지의 구조화된 콘텐츠를 마크다운으로 변환합니다
웹/텍스트 CSV, JSON, XML 내장 파서 구조화된 텍스트 데이터를 마크다운 형식으로 정리합니다
미디어 이미지 (JPG, PNG 등) EXIF + LLM Vision EXIF 메타데이터를 추출하고, LLM 클라이언트 연동 시 이미지 설명과 OCR을 수행합니다
미디어 오디오 (MP3, WAV) speech_recognition 음성을 텍스트로 변환(Speech-to-Text)합니다. LLM 클라이언트가 필요합니다
기타 EPub 내장 파서 전자책 콘텐츠를 마크다운으로 변환합니다
기타 ZIP 내장 파서 아카이브 내부의 파일들을 순회하며 각각 변환합니다
기타 Outlook MSG 내장 파서 이메일 메시지의 본문과 메타데이터를 추출합니다
기타 YouTube URL youtube-transcript-api 영상의 자동 생성 자막(트랜스크립트)을 마크다운으로 변환합니다

핵심 가치 3가지

MarkItDown의 설계 철학은 세 가지 핵심 가치로 요약할 수 있습니다. 이 가치들을 이해하면 이 도구를 어떤 상황에서 사용해야 하는지, 그리고 어떤 상황에서는 다른 도구를 선택해야 하는지를 판단하는 데 도움이 됩니다.

 

첫째, 구조 보존(Structure Preservation)입니다.

MarkItDown은 단순히 텍스트를 추출하는 것이 아니라, 원본 문서의 구조적 요소들을 마크다운 문법으로 매핑합니다. Word 문서의 Heading 1은 마크다운의 #으로, Heading 2는 ##으로 변환되며, 번호 목록은 1. 2. 3.으로, 글머리 기호 목록은 - - -으로 변환됩니다. 표(table)는 마크다운 테이블 문법(| |)으로, 하이퍼링크는 [텍스트](URL) 형식으로 보존됩니다. 이런 구조 보존 덕분에 LLM은 변환된 마크다운을 읽을 때 "이 부분이 제목이고, 이 부분이 하위 항목이며, 이 데이터가 표 형태로 정리되어 있다"는 것을 정확히 파악할 수 있습니다.

 

둘째, LLM 최적화(LLM-First Design)입니다.

MarkItDown의 공식 문서에는 매우 중요한 문장이 있습니다. "출력은 대체로 사람이 읽기에도 합리적이고 친화적이지만, 텍스트 분석 도구에 의해 소비되도록 설계되었습니다(it is meant to be consumed by text analysis tools)." 즉, 이 도구는 사람이 읽기 위한 고충실도(high-fidelity) 문서 변환이 아니라, AI가 효율적으로 처리할 수 있는 구조화된 텍스트 생성을 목표로 합니다. 색상, 글꼴 크기, 여백 같은 시각적 서식은 과감히 버리고, 의미 있는 구조만 남깁니다. 이런 접근 방식은 토큰 효율성을 극대화하고, LLM이 핵심 내용에 집중할 수 있게 해줍니다.

 

셋째, 확장성(Extensibility)입니다.

MarkItDown은 플러그인 시스템을 통해 기능을 확장할 수 있도록 설계되었습니다. 예를 들어, markitdown-ocr 플러그인은 PDF, DOCX, PPTX, XLSX 파일에 포함된 이미지에서 텍스트를 추출하는 OCR 기능을 추가합니다. 커뮤니티는 GitHub에서 #markitdown-plugin 해시태그로 자신이 만든 플러그인을 공유할 수 있으며, 플러그인 개발을 위한 샘플 코드(markitdown-sample-plugin)도 제공됩니다. 또한 llm_client 파라미터를 통해 OpenAI, Claude, Gemini 등 다양한 LLM 클라이언트를 연동하여 이미지 캡셔닝, OCR, 오디오 트랜스크립션 같은 멀티모달 처리를 수행할 수 있습니다.

성능 벤치마크

MarkItDown의 성능을 객관적으로 이해하기 위해 외부 벤치마크 결과를 살펴보겠습니다. 독립적인 테스트에 따르면, MarkItDown은 소규모 파일 기준으로 초당 180개 이상의 파일을 처리할 수 있으며, 평균 메모리 사용량은 약 253MB에 불과합니다. 이는 IBM의 Docling과 비교하면 약 100배 빠른 속도이며, Kreuzberg와 비교해도 약 3배 빠른 수준입니다. 가볍고 빠른 처리 속도는 대량의 문서를 일괄 변환해야 하는 RAG 파이프라인 전처리 단계에서 큰 장점이 됩니다.

 

다만 속도와 정확도 사이에는 트레이드오프가 존재합니다. 외부 벤치마크에서 MarkItDown의 전체 변환 성공률은 약 47.3%로 측정되었으며, PDF에 한정하면 성공률이 약 25%까지 떨어집니다. 이 수치가 의미하는 것은, 변환된 결과물의 약 절반 정도에서 구조 손실이나 텍스트 누락 같은 문제가 발생할 수 있다는 것입니다. 특히 복잡한 레이아웃을 가진 PDF(다단 구성, 수식, 복잡한 표)에서 이런 문제가 두드러집니다. 반면 Docling은 AI 기반 레이아웃 분석을 통해 훨씬 높은 정확도를 달성하지만, 그만큼 처리 시간과 리소스 소비가 큽니다. 이러한 트레이드오프는 뒤에서 다룰 "도구 선택 가이드"에서 더 자세히 비교하겠습니다.

MarkItDown은 각 파일 형식에 최적화된 파서를 선택한 뒤 통합된 마크다운으로 변환하는 2단계 아키텍처를 사용합니다
MarkItDown은 각 파일 형식에 최적화된 파서를 선택한 뒤 통합된 마크다운으로 변환하는 2단계 아키텍처를 사용합니다

4. MarkItDown의 제한점과 주의사항

어떤 도구든 만능은 아닙니다. MarkItDown을 실무에 도입하기 전에 반드시 알아야 할 제한점들을 정리합니다. 이 제한점들을 미리 인지하고 있으면, 적절한 대처 전략을 세울 수 있고, 도구 선택 시 불필요한 시행착오를 줄일 수 있습니다.

PDF 처리의 근본적 한계

MarkItDown의 PDF 변환은 pdfminer.six 라이브러리에 의존합니다. pdfminer.six는 PDF 파일에서 텍스트를 추출하는 데 특화된 도구이지만, 레이아웃 분석(layout analysis) 기능은 제한적입니다. 이 때문에 다음과 같은 상황에서 문제가 발생할 수 있습니다.

  • 스캔된 PDF(이미지 기반 PDF)는 처리할 수 없습니다.
    pdfminer.six는 PDF 내부의 텍스트 객체만 추출하므로, 종이 문서를 스캔하여 만든 이미지 기반 PDF에서는 아무런 텍스트도 추출하지 못합니다. 이 경우 markitdown-ocr 플러그인을 설치하거나, Azure Document Intelligence 같은 외부 OCR 서비스를 연동해야 합니다.
  • 복잡한 레이아웃에서 구조가 손실됩니다.
    다단(multi-column) 구성, 복잡한 표, 수식, 그래프가 포함된 PDF에서는 텍스트의 읽기 순서가 뒤섞이거나, 표의 행과 열이 올바르게 인식되지 않는 경우가 빈번합니다. 학술 논문이나 금융 보고서처럼 정교한 레이아웃을 가진 문서에서는 Docling이나 Marker 같은 도구가 더 적합합니다.
  • 제목과 본문의 구분이 정확하지 않습니다.
    PDF는 근본적으로 "시각적 렌더링"을 위한 형식이므로, 어떤 텍스트가 제목이고 어떤 텍스트가 본문인지에 대한 의미적 정보가 없는 경우가 많습니다. MarkItDown은 폰트 크기나 볼드 여부 등을 기반으로 추론하지만, 항상 정확한 것은 아닙니다.

이미지 및 오디오 처리의 외부 의존성

MarkItDown은 이미지 캡셔닝(이미지 내용을 텍스트로 설명), OCR(이미지에서 텍스트 추출), 오디오 트랜스크립션(음성을 텍스트로 변환) 기능을 제공하지만, 이 기능들은 모두 외부 LLM 클라이언트(주로 OpenAI API)에 의존합니다. 즉, OpenAI API 키가 없으면 이미지와 오디오 파일은 EXIF 메타데이터만 추출되고, 실제 콘텐츠는 변환되지 않습니다. 이는 로컬 환경에서 외부 API 없이 완전히 독립적으로 운영하고 싶은 경우에 제약이 됩니다. 다만 OpenAI 호환 API를 제공하는 Local LLM(Ollama, llama.cpp 등)을 llm_client로 연동하면 이 제약을 해소할 수 있으며, 이 방법은 11장에서 자세히 다루겠습니다.

고충실도 변환에는 부적합

MarkItDown은 명확하게 "사람이 읽기 위한 고충실도 변환에는 최적의 선택이 아닐 수 있다(may not be the best option for high-fidelity document conversions for human consumption)"고 밝히고 있습니다. 이 도구의 설계 철학은 AI 파이프라인을 위한 효율적인 텍스트 추출이지, 원본 문서의 시각적 모양을 완벽하게 재현하는 것이 아닙니다. 따라서 색상, 글꼴, 여백, 페이지 레이아웃 같은 시각적 서식 정보는 모두 손실됩니다. 만약 사람이 읽기 위한 형식 변환이 필요하다면(예: Word를 PDF로, 마크다운을 HTML로), Pandoc이 더 적합한 선택입니다.

알려진 이슈와 실무 권장사항

GitHub 이슈 트래커에서 확인된 주요 문제로는 HTML의 동적 데이터 변환 시 데이터 손실, PDF 내 이미지 링크 추출 오류 등이 있습니다. 이러한 제한점들을 감안할 때, 실무에서는 MarkItDown을 "1차 변환기(first-pass converter)"로 활용하고, 변환 품질이 중요한 문서에 대해서는 Docling이나 Kreuzberg 같은 정확도 높은 도구로 폴백(fallback)하는 티어드(tiered) 파이프라인 전략을 권장합니다.

flowchart TD
    A["문서 입력"] --> B{"파일 형식?"}
    B -->|"Office 문서\n(DOCX/PPTX/XLSX)"| C["MarkItDown\n변환 실행"]
    B -->|"텍스트 기반 PDF"| C
    B -->|"HTML/CSV/JSON"| C
    B -->|"스캔된 PDF\n이미지 기반"| D["Docling 또는\nAzure Doc Intel"]
    B -->|"복잡한 레이아웃 PDF\n학술 논문/금융 보고서"| D
    C --> E{"변환 품질\n검증"}
    E -->|"성공\n구조 보존됨"| F["마크다운 출력\nLLM 파이프라인 투입"]
    E -->|"실패\n구조 손실/텍스트 누락"| D
    D --> G["고정밀 마크다운 출력"]
    G --> F

    style C fill:#4A90D9,stroke:#333,color:#fff
    style D fill:#E67E22,stroke:#333,color:#fff
    style F fill:#2ECC71,stroke:#333,color:#fff

[i] 참고: 위 플로우차트는 실무에서 권장되는 "티어드 파이프라인" 전략을 보여줍니다. MarkItDown이 처리하기 어려운 문서는 Docling 같은 AI 기반 도구로 자동 전환하여 전체 파이프라인의 성공률을 높일 수 있습니다.

5. 기존 솔루션 비교  |  MarkItDown vs Docling vs Pandoc vs Marker vs MinerU

문서를 마크다운으로 변환하는 도구는 MarkItDown만 있는 것이 아닙니다. 각 도구는 서로 다른 철학과 기술적 접근 방식을 가지고 있으며, 어떤 도구가 "최고"인지는 사용 목적에 따라 달라집니다. 이 장에서는 대표적인 5가지 오픈소스 문서 변환 도구를 객관적으로 비교하여, 독자가 자신의 상황에 맞는 최적의 도구를 선택할 수 있도록 안내합니다.

5대 도구 개요

MarkItDown (Microsoft) 은 이 글의 주인공으로, "가볍고 빠르게, 다양한 형식을" 변환하는 데 초점을 맞추고 있습니다. AutoGen 프로젝트에서 탄생한 만큼, AI 에이전트가 문서를 읽는 도구로 사용되는 것이 주된 목적입니다. MIT 라이선스로 상업적 사용에 제한이 없으며, MCP 서버를 통해 Claude Desktop 같은 AI 클라이언트와 직접 통합할 수 있는 것이 독보적인 장점입니다. 다만 PDF 변환 정확도는 다른 전문 도구에 비해 낮은 편입니다.

 

Docling (IBM) 은 AI 기반 레이아웃 분석에 특화된 도구입니다. Hugging Face의 딥러닝 모델을 활용하여 문서의 시각적 레이아웃을 분석하고, 읽기 순서를 정확하게 판단합니다. 복잡한 표, 다단 구성, 과학 논문 같은 난이도 높은 문서에서 뛰어난 정확도를 보여주지만, 모델 다운로드와 추론 과정 때문에 처리 속도가 느리고 디스크 공간과 메모리를 많이 사용합니다. PDF와 DOCX 변환에 강점이 있으며, 마크다운과 JSON 형식으로 출력할 수 있습니다.

 

Pandoc 은 "문서 변환의 스위스 아미 나이프"로 불리는 도구로, 60개 이상의 입출력 형식을 지원합니다. 마크다운, HTML, LaTeX, PDF, DOCX, EPUB, reStructuredText 등 거의 모든 문서 형식 간의 양방향 변환이 가능합니다. Pandoc의 강점은 서식 충실도(formatting fidelity)에 있으며, 사람이 읽기 위한 고품질 문서 변환에 최적화되어 있습니다. 다만 AI 파이프라인용으로 설계된 것이 아니므로, LLM 통합 기능이나 MCP 서버 같은 기능은 없습니다.

 

Marker 는 PDF를 마크다운과 JSON으로 변환하는 데 특화된 도구입니다. 학술 논문이나 책처럼 잘 구조화된 문서에서 높은 구조 충실도(structure fidelity)를 보여주며, 표와 이미지 처리 성능도 우수합니다. 다만 상업적 사용에 제한이 있는 라이선스(GPL)를 사용하므로, 기업 환경에서 도입할 때는 라이선스 검토가 필요합니다. 여러 가지 사용 모드(CLI, API, 서버)를 제공하여 유연하게 활용할 수 있습니다.

 

MinerU 는 복잡한 표를 HTML 렌더링으로 처리하는 능력이 뛰어난 도구입니다. 변환 속도도 빠른 편이며, 오픈 라이선스를 사용합니다. 다만 이미지 처리 부분에서 가끔 이미지가 불완전하게 크롭(crop)되는 문제가 보고되고 있으며, PDF 문서의 아웃라인(목차 구조) 인식 정확도가 완벽하지 않을 수 있습니다.

종합 비교 테이블

비교기준 MarkItDown Docling Pandoc Marker MinerU
개발사 Microsoft IBM 커뮤니티 개인(VikParuchuri) 커뮤니티
라이선스 MIT (자유) MIT GPL-2.0 GPL (제한) Apache 2.0
주요 언어 Python Python Haskell Python Python
지원 입력 형식 수 15+ 형식 5+ 형식 (PDF, DOCX 중심) 60+ 형식 PDF 전문 PDF 전문
출력 형식 마크다운 마크다운, JSON 60+ 형식 마크다운, JSON 마크다운
처리 속도 매우 빠름 (180+ files/sec) 느림 (AI 모델 추론) 보통 보통 빠름
메모리 사용 낮음 (~253MB) 높음 (모델 로딩) 낮음 보통 보통
PDF 정확도 낮음 (25% 성공률) 높음 (AI 레이아웃 분석) 보통 (잘 구조화된 PDF) 높음 (학술 논문 특화) 높음 (복잡한 표 강점)
표 처리 기본 우수 보통 우수 우수 (HTML 렌더링)
수식 처리 미지원 지원 지원 (LaTeX) 지원 지원
OCR 지원 플러그인 (markitdown-ocr) 내장 (AI 모델) 미지원 미지원 미지원
LLM 통합 내장 (llm_client) 없음 없음 없음 없음
MCP 서버 공식 지원 커뮤니티 커뮤니티 없음 없음
양방향 변환 아니오 (입력->MD만) 아니오 예 (모든 방향) 아니오 아니오
GitHub 스타 87K+ 20K+ 35K+ 18K+ 25K+

시나리오별 선택 가이드

도구를 선택할 때 가장 중요한 것은 "무엇을 변환하느냐"와 "왜 변환하느냐"입니다. 아래는 대표적인 시나리오별 추천 도구를 정리한 것입니다.

  • 대량의 다양한 형식 문서를 빠르게 전처리해야 할 때 -> MarkItDown.
    RAG 파이프라인의 전처리 단계에서 Word, Excel, PowerPoint, HTML, PDF 등 다양한 형식의 문서를 일괄 변환해야 한다면, MarkItDown의 속도와 형식 범위가 가장 큰 장점이 됩니다. 변환 품질이 완벽하지 않더라도, 대량 처리 후 문제 있는 파일만 후처리하는 전략이 효율적입니다.
  • 복잡한 PDF 문서의 정확한 변환이 필요할 때 -> Docling 또는 Marker.
    학술 논문, 금융 보고서, 기술 매뉴얼처럼 다단 레이아웃, 복잡한 표, 수식이 포함된 PDF를 변환할 때는 AI 기반 레이아웃 분석을 제공하는 Docling이 적합합니다. 특히 책이나 논문처럼 잘 구조화된 문서에는 Marker도 좋은 선택입니다.
  • 문서 형식 간 양방향 변환이 필요할 때 -> Pandoc.
    마크다운을 PDF로, HTML을 DOCX로, LaTeX를 EPUB로 변환하는 등 "출력 형식의 다양성"이 필요하다면 Pandoc이 유일한 선택지입니다. MarkItDown과 Docling은 입력->마크다운 방향만 지원하므로, 문서 생성(document creation)에는 적합하지 않습니다.
  • 상업적 프로젝트에서 라이선스 제약 없이 사용하고 싶을 때 -> MarkItDown(MIT) 또는 MinerU(Apache 2.0).
    Marker는 GPL 라이선스이므로 상업적 사용 시 제약이 있을 수 있습니다. 라이선스 자유도가 중요한 기업 환경에서는 MIT 라이선스의 MarkItDown이나 Apache 2.0의 MinerU가 안전한 선택입니다.
  • AI 에이전트에 문서 읽기 도구를 제공하고 싶을 때 -> MarkItDown.
    MCP 서버를 공식 지원하는 유일한 도구이며, AutoGen 같은 멀티 에이전트 프레임워크와의 통합이 가장 매끄럽습니다. Claude Desktop, Cursor 같은 AI 클라이언트에 네이티브 도구로 등록하여, 사용자의 프롬프트에 따라 문서를 실시간으로 변환하고 분석하는 워크플로우를 구성할 수 있습니다.

하이브리드 전략  |  최적의 실전 접근법

실무에서 가장 효과적인 접근법은 단일 도구에 의존하는 것이 아니라, 여러 도구를 조합하는 하이브리드 전략입니다. 일반적으로 권장되는 패턴은 다음과 같습니다. MarkItDown을 1차 변환기로 사용하여 모든 문서를 빠르게 변환한 뒤, 변환 품질을 자동 또는 수동으로 검증합니다. 이때 구조가 심하게 손실되거나 텍스트가 누락된 문서를 발견하면, 해당 파일만 Docling이나 Kreuzberg 같은 정밀 도구로 재변환합니다. 이렇게 하면 대부분의 문서는 빠르게 처리하면서도, 품질이 중요한 소수의 문서에 대해서는 높은 정확도를 확보할 수 있습니다.

6. MarkItDown 설치 및 환경 구성

MarkItDown의 설치는 매우 간단합니다. Python 패키지 관리자 pip을 사용하면 한 줄의 명령어로 설치가 완료됩니다. 다만 처리하려는 파일 형식에 따라 선택적으로 의존성을 설치할 수 있으므로, 자신의 환경에 맞는 최적의 설치 방법을 선택하는 것이 좋습니다. 이 장에서는 기본 설치부터 Docker 기반 격리 환경 구성까지 단계별로 안내합니다.

시스템 요구사항

MarkItDown을 사용하려면 Python 3.10 이상이 필요합니다. 설치 전에 터미널에서 아래 명령어로 Python 버전을 확인합니다.

python --version
# 또는
python3 --version
# 출력 예시: Python 3.12.4

Python 3.10 미만인 경우, Python 공식 사이트(python.org)에서 최신 버전을 설치하거나, pyenv 같은 버전 관리 도구를 사용하여 업그레이드할 수 있습니다.

가상 환경 구성

다른 Python 프로젝트와의 의존성 충돌을 방지하기 위해, 가상 환경(virtual environment)을 먼저 만드는 것을 권장합니다. Python에는 여러 가지 가상 환경 도구가 있으며, 상황에 맞게 선택할 수 있습니다.

# 방법 1: 표준 venv 사용
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# 방법 2: uv 사용 (최신 고속 패키지 관리자)
uv venv --python=3.12 .venv
source .venv/bin/activate
# [!] uv 환경에서는 'uv pip install'을 사용해야 합니다

# 방법 3: Anaconda 사용
conda create -n markitdown python=3.12
conda activate markitdown

설치 방법

가상 환경이 활성화된 상태에서, 아래 3가지 방법 중 하나를 선택하여 MarkItDown을 설치합니다.

방법 1  |  전체 설치 (가장 간단, 모든 파일 형식 지원)

pip install 'markitdown[all]'

이 명령어는 MarkItDown과 모든 선택적 의존성(PDF, DOCX, PPTX, XLSX, 오디오, YouTube 등)을 한 번에 설치합니다. 빠르게 시작하고 싶다면 이 방법을 추천합니다. 다만 불필요한 패키지까지 설치되므로 디스크 공간과 설치 시간이 다소 늘어날 수 있습니다.

방법 2  |  선택적 설치 (필요한 형식만 설치)

# 오피스 문서만 처리하는 경우
pip install 'markitdown[pdf,docx,pptx,xlsx]'

# PDF만 처리하는 경우
pip install 'markitdown[pdf]'

# 오디오 트랜스크립션이 필요한 경우
pip install 'markitdown[audio-transcription]'

# YouTube 자막 추출이 필요한 경우
pip install 'markitdown[youtube-transcription]'

사용 가능한 의존성 그룹은 다음과 같습니다: all, pdf, pptx, docx, xlsx, xls, outlook, az-doc-intel, audio-transcription, youtube-transcription. 경량 환경이나 서버 배포 시에는 필요한 그룹만 선택적으로 설치하여 컨테이너 이미지 크기를 줄일 수 있습니다.

방법 3  |  소스에서 설치 (개발 또는 최신 기능 사용)

git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

소스 설치는 최신 개발 중인 기능을 사용하거나, 코드를 수정하여 기여(contribute)하고 싶을 때 유용합니다. -e 옵션은 "편집 가능(editable) 모드"로 설치하여, 소스 코드를 수정하면 바로 반영되게 합니다.

설치 검증

설치가 완료되면 아래 명령어로 정상 설치를 확인합니다.

markitdown --version
# 출력 예시: markitdown 0.1.5

버전 정보가 출력되면 설치가 성공한 것입니다. 만약 command not found 오류가 발생한다면, 가상 환경이 활성화되어 있는지 확인하거나, python -m markitdown --version으로 시도해 보시기 바랍니다.

플러그인 및 추가 패키지 설치

MarkItDown은 코어 기능 외에 플러그인과 MCP 서버 패키지를 별도로 제공합니다. 필요에 따라 아래 패키지를 추가 설치할 수 있습니다.

# OCR 플러그인 (PDF/DOCX 내 이미지에서 텍스트 추출)
pip install markitdown-ocr

# MCP 서버 (Claude Desktop, AI 에이전트 연동)
pip install markitdown-mcp

# 설치된 플러그인 확인
markitdown --list-plugins

Docker 기반 설치

Python 환경을 직접 구성하지 않고, Docker 컨테이너로 격리된 환경에서 MarkItDown을 사용할 수도 있습니다. Docker를 사용하면 호스트 시스템에 아무것도 설치하지 않아도 되며, 사용이 끝난 후 컨테이너를 삭제하면 깨끗하게 정리됩니다.

# 공식 Dockerfile로 이미지 빌드
git clone git@github.com:microsoft/markitdown.git
cd markitdown
docker build -t markitdown:latest .

# stdin으로 파일 변환
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

# 로컬 디렉토리를 마운트하여 사용
docker run -it --rm -v $(pwd):/workdir markitdown:latest \
  markitdown /workdir/document.docx > /workdir/output.md

[i] 참고: Docker 사용 시 로컬 파일에 접근하려면 반드시 -v 옵션으로 디렉토리를 마운트해야 합니다. 마운트하지 않으면 컨테이너 내부에서 호스트의 파일을 읽을 수 없습니다.

 

flowchart TD
    A["MarkItDown 설치 시작"] --> B{"사용 목적?"}
    B -->|"빠르게 시작\n모든 형식 필요"| C["pip install\n'markitdown[all]'"]
    B -->|"특정 형식만\n경량 설치"| D["pip install\n'markitdown[pdf,docx,...]'"]
    B -->|"개발/기여\n최신 기능"| E["git clone +\npip install -e"]
    B -->|"격리 환경\nPython 미설치"| F["Docker\nbuild + run"]
    C --> G{"추가 기능?"}
    D --> G
    E --> G
    F --> H["사용 시작"]
    G -->|"OCR 필요"| I["pip install\nmarkitdown-ocr"]
    G -->|"AI 클라이언트 연동"| J["pip install\nmarkitdown-mcp"]
    G -->|"추가 불필요"| H
    I --> H
    J --> H

    style A fill:#4A90D9,stroke:#333,color:#fff
    style H fill:#2ECC71,stroke:#333,color:#fff

7. MarkItDown CLI 활용 가이드

MarkItDown은 터미널에서 markitdown 명령어로 바로 사용할 수 있는 CLI(Command-Line Interface)를 제공합니다. CLI는 파일 하나를 빠르게 변환하는 것부터, Unix 파이프라인과 조합하여 복잡한 워크플로우를 구성하는 것까지 다양한 사용 패턴을 지원합니다. 이 장에서는 기본 사용법부터 고급 활용 팁까지 실전 중심으로 안내합니다.

기본 변환 명령어

가장 단순한 사용법은 파일 경로를 인자로 전달하는 것입니다. 별도의 출력 옵션을 지정하지 않으면 변환 결과가 터미널(stdout)에 출력됩니다.

# 기본: 변환 결과를 터미널에 출력
markitdown report.pdf

# -o 옵션: 결과를 파일로 저장
markitdown report.pdf -o report.md

# 리다이렉션: 셸의 > 연산자로 파일 저장 (동일 효과)
markitdown report.pdf > report.md

다양한 파일 형식에 대해 동일한 명령어 패턴으로 변환할 수 있습니다. MarkItDown이 파일 확장자를 자동으로 감지하여 적절한 내부 파서를 선택합니다.

# Word 문서 변환
markitdown contract.docx -o contract.md

# PowerPoint 변환
markitdown presentation.pptx -o slides.md

# Excel 변환
markitdown data.xlsx -o data.md

# HTML 변환
markitdown webpage.html -o page.md

# EPub 전자책 변환
markitdown book.epub -o book.md

# ZIP 아카이브 내부 전체 변환
markitdown documents.zip -o archive_contents.md

stdin 입력과 파이프라인 활용

MarkItDown은 파일 경로를 직접 지정하는 방법 외에도, stdin(표준 입력)을 통해 데이터를 받을 수 있습니다. 이 기능은 Unix 파이프라인과 조합하면 매우 강력한 워크플로우를 구성할 수 있게 해줍니다. 다만 stdin으로 입력할 때는 파일 확장자를 자동 감지할 수 없으므로, -x(확장자 힌트) 옵션을 함께 제공해야 합니다.

# curl로 원격 파일 다운로드 후 바로 변환
curl https://example.com/document.pdf | markitdown -x .pdf > output.md

# cat으로 파일 내용을 파이프로 전달
cat mystery_file | markitdown -x .xlsx -o output.md

# 변환 후 단어 수 세기
markitdown document.docx | wc -w

# 변환 후 특정 키워드 검색
markitdown report.pdf | grep "quarterly results"

# 변환 후 첫 50줄만 미리보기
markitdown large_doc.pdf | head -50

# 변환 후 라인 수 확인
markitdown slides.pptx | wc -l

형식 힌트 옵션

stdin 입력 시 또는 파일 형식이 자동 감지되지 않을 때, 아래 옵션으로 형식 정보를 직접 제공할 수 있습니다. 이 옵션들은 MarkItDown 내부에서 StreamInfo 객체를 생성하는 데 사용됩니다.

옵션 단축 설명 사용 예시
--extension -x 파일 확장자 힌트. 선행 .은 자동 추가되며 소문자로 정규화됩니다 markitdown -x .pdf < doc
--mime-type -m MIME 타입 힌트. / 구분자가 정확히 1개여야 합니다 markitdown -m application/pdf < doc
--charset -c 문자 인코딩 힌트. codecs.lookup()으로 검증됩니다 markitdown -c ISO-8859-1 -x .txt < legacy 
# 확장자 힌트 (선행 점 자동 추가 - .pdf와 pdf 모두 동작)
markitdown -x .pdf < document
markitdown --extension pdf < document  # 동일 효과

# MIME 타입 힌트
markitdown -m application/pdf < document
markitdown --mime-type application/pdf < document

# 인코딩 힌트 (비UTF-8 파일 처리)
markitdown -c ISO-8859-1 -x .txt < legacy_file.txt
markitdown --charset UTF-8 < document

Azure Document Intelligence 연동

복잡한 PDF 문서를 더 정확하게 변환하고 싶다면, Azure Document Intelligence(클라우드 기반 문서 분석 서비스)를 연동할 수 있습니다. 이 기능을 사용하려면 Azure 계정에서 Document Intelligence 리소스를 먼저 생성해야 합니다.

# 기본 사용법
markitdown path-to-file.pdf -o document.md \
  -d -e "https://YOUR_ENDPOINT.cognitiveservices.azure.com/"

# 전체 옵션 명시
markitdown --use-docintel \
  --endpoint "https://YOUR_ENDPOINT.cognitiveservices.azure.com/" \
  complex_report.pdf -o output.md

[!] 주의: Azure Document Intelligence 모드에서는 반드시 파일명을 직접 지정해야 합니다. stdin(파이프/리다이렉션) 입력은 지원되지 않으며, --endpoint 옵션도 필수입니다.

플러그인 관리

MarkItDown은 3rd-party 플러그인을 통해 기능을 확장할 수 있습니다. 플러그인은 기본적으로 비활성화되어 있으므로, 사용하려면 명시적으로 활성화해야 합니다.

# 설치된 플러그인 목록 확인
markitdown --list-plugins
# 출력 예시:
# Installed MarkItDown 3rd-party Plugins:
#   * ocr_plugin (package: markitdown_ocr)

# 플러그인을 활성화하여 변환
markitdown -p document_with_images.pdf -o output.md
markitdown --use-plugins scanned_document.pdf -o output.md

[i] 참고: GitHub에서 #markitdown-plugin 해시태그를 검색하면 커뮤니티에서 만든 다양한 플러그인을 찾을 수 있습니다. 플러그인 개발에 관심이 있다면 공식 리포지토리의 packages/markitdown-sample-plugin 디렉토리를 참고하시기 바랍니다.

docpler/markitdown-hwp 리포지토리의 플러그인을 설치하면, HWP문서도 읽을 수 있습니다.

기타 유용한 옵션

# 버전 확인
markitdown -v
markitdown --version

# base64 data URI를 출력에 유지 (기본값: 잘라냄)
# 이미지가 포함된 HTML 등에서 유용하지만 파일 크기가 크게 증가합니다
markitdown --keep-data-uris image_doc.html -o output.md

CLI 옵션 치트시트

아래는 MarkItDown CLI의 모든 옵션을 한눈에 볼 수 있는 치트시트입니다. 이 표를 참고하면 작업 시 필요한 옵션을 빠르게 찾을 수 있습니다.

옵션 단축 용도 필수 조건
--version -v 버전 출력 후 종료 없음
--output FILE -o FILE 결과를 파일로 저장 없음
--help -h 도움말 표시 후 종료 없음
--extension EXT -x EXT 파일 확장자 힌트 stdin 입력 시 권장
--mime-type TYPE -m TYPE MIME 타입 힌트 stdin 입력 시 선택
--charset CHARSET -c CHARSET 문자 인코딩 힌트 비UTF-8 파일 시
--use-docintel -d Azure Doc Intel 활성화 -e 필수, 파일명 필수
--endpoint URL -e URL Azure Doc Intel 엔드포인트 -d와 함께 사용
--use-plugins -p 3rd-party 플러그인 활성화 플러그인 사전 설치
--list-plugins (없음) 설치된 플러그인 목록 표시 없음
--keep-data-uris (없음) base64 data URI 유지 없음

배치 변환 스크립트

여러 파일을 한꺼번에 변환해야 할 때는 셸 스크립트를 활용하면 효율적입니다. 아래는 특정 디렉토리 내의 모든 지원 파일을 마크다운으로 일괄 변환하는 Bash 스크립트 예시입니다.

#!/bin/bash
# 디렉토리 내 모든 지원 파일을 마크다운으로 일괄 변환

INPUT_DIR="./documents"
OUTPUT_DIR="./markdown_output"
mkdir -p "$OUTPUT_DIR"

for file in "$INPUT_DIR"/*.{pdf,docx,pptx,xlsx,html}; do
    [ -f "$file" ] || continue
    filename=$(basename "$file")
    name="${filename%.*}"
    echo "Converting: $filename"
    markitdown "$file" -o "$OUTPUT_DIR/${name}.md" 2>/dev/null
    if [ $? -eq 0 ]; then
        echo "  [v] Success: ${name}.md"
    else
        echo "  [!] Failed: $filename"
    fi
done

echo "---"
echo "Conversion complete. Output: $OUTPUT_DIR"

위 스크립트는 ./documents 디렉토리에서 PDF, DOCX, PPTX, XLSX, HTML 파일을 찾아 각각 마크다운으로 변환하고, 결과를 ./markdown_output 디렉토리에 저장합니다. 변환 성공/실패 여부를 터미널에 출력하므로, 어떤 파일이 문제가 있는지 쉽게 확인할 수 있습니다.

8. Python API를 활용한 프로그래밍 통합

CLI가 터미널에서 빠르게 파일을 변환하는 데 적합하다면, Python API는 MarkItDown을 프로그램 내부에 통합하여 자동화된 파이프라인을 구축하는 데 적합합니다. Python 코드에서 MarkItDown을 사용하면 변환 결과를 바로 후처리하거나, LLM 클라이언트와 연동하여 이미지 캡셔닝이나 OCR 같은 고급 기능을 활용할 수 있습니다. 이 장에서는 기본 사용법부터 LLM 연동, 배치 처리, 에러 핸들링까지 실전 코드를 중심으로 안내합니다.

기본 사용법

MarkItDown Python API의 핵심은 매우 단순합니다. MarkItDown 클래스의 인스턴스를 생성하고, convert() 메서드에 파일 경로를 전달하면 변환이 완료됩니다. 변환 결과는 result.text_content 속성으로 접근할 수 있습니다.

from markitdown import MarkItDown

# MarkItDown 인스턴스 생성 (플러그인 비활성화)
md = MarkItDown(enable_plugins=False)

# 파일 변환
result = md.convert("test.xlsx")

# 변환된 마크다운 텍스트 출력
print(result.text_content)

위 코드가 MarkItDown의 전부라고 해도 과언이 아닙니다. 단 4줄의 코드로 Excel 파일을 마크다운으로 변환할 수 있습니다. convert() 메서드는 파일 확장자를 자동으로 감지하여 적절한 내부 파서를 선택하므로, PDF든 Word든 동일한 코드 패턴으로 변환할 수 있습니다. URL을 직접 전달하여 웹 페이지를 변환하는 것도 가능합니다.

# URL 직접 변환
result = md.convert("https://example.com/page.html")
print(result.text_content)

LLM 클라이언트 연동  |  이미지 캡셔닝 / OCR

이미지나 PowerPoint 슬라이드에 포함된 이미지를 텍스트로 변환하려면, LLM 클라이언트를 연동해야 합니다. MarkItDown은 OpenAI 호환 클라이언트를 llm_client 파라미터로 받아, Vision 모델을 활용하여 이미지 설명을 생성하거나 OCR을 수행합니다.

from markitdown import MarkItDown
from openai import OpenAI

# OpenAI 클라이언트 설정
client = OpenAI()  # OPENAI_API_KEY 환경변수 필요

# LLM 클라이언트를 연동한 MarkItDown 인스턴스 생성
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="Describe this image in detail for documentation purposes"
)

# 이미지 파일 변환 (LLM이 이미지 설명 생성)
result = md.convert("diagram.png")
print(result.text_content)

# PowerPoint 슬라이드 내 이미지도 자동 캡셔닝
result = md.convert("presentation.pptx")
print(result.text_content)

OpenAI 이외의 LLM을 사용하고 싶다면, OpenAI 호환 API를 제공하는 서비스를 활용할 수 있습니다. 예를 들어, OpenRouter를 통해 Claude 모델을 연동하는 방법은 다음과 같습니다.

from markitdown import MarkItDown
from openai import OpenAI

# OpenRouter를 통한 Claude 모델 연동
client = OpenAI(
    api_key="your-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-sonnet-4-20250514",
    llm_prompt="Describe this image in detail for scientific documentation"
)

result = md.convert("scientific_figure.png")
print(result.text_content)

OCR 플러그인 활용

markitdown-ocr 플러그인을 설치하면, PDF, DOCX, PPTX, XLSX 파일에 포함된 이미지에서 텍스트를 추출하는 OCR 기능이 활성화됩니다. 이 플러그인은 MarkItDown이 이미 사용하고 있는 llm_client/llm_model 패턴을 그대로 활용하므로, 별도의 ML 라이브러리나 바이너리 의존성이 필요하지 않습니다.

from markitdown import MarkItDown
from openai import OpenAI

# OCR 플러그인 활성화
md = MarkItDown(
    enable_plugins=True,           # 플러그인 활성화
    llm_client=OpenAI(),           # LLM Vision으로 OCR 수행
    llm_model="gpt-4o",
)

# 이미지가 포함된 PDF에서 텍스트 추출
result = md.convert("document_with_images.pdf")
print(result.text_content)

[i] 참고: llm_client를 제공하지 않으면 OCR 플러그인이 로드되더라도 OCR은 건너뛰고 표준 내장 변환기가 사용됩니다. 즉, 플러그인 활성화만으로는 OCR이 동작하지 않으며, LLM 클라이언트가 반드시 함께 설정되어야 합니다.

Azure Document Intelligence 연동

Azure Document Intelligence는 Microsoft의 클라우드 기반 문서 분석 서비스로, 복잡한 레이아웃의 PDF도 높은 정확도로 변환할 수 있습니다. Python API에서는 docintel_endpoint 파라미터로 연동합니다.

from markitdown import MarkItDown

# Azure Document Intelligence 연동
md = MarkItDown(
    docintel_endpoint="https://YOUR_ENDPOINT.cognitiveservices.azure.com/"
)

result = md.convert("complex_report.pdf")
print(result.text_content)

배치 변환과 에러 핸들링

실무에서는 디렉토리 내의 여러 파일을 순회하며 일괄 변환하는 경우가 많습니다. 이때 일부 파일에서 오류가 발생하더라도 전체 프로세스가 중단되지 않도록 적절한 에러 핸들링이 필요합니다.

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown(enable_plugins=False)

input_dir = Path("./documents")
output_dir = Path("./markdown_output")
output_dir.mkdir(exist_ok=True)

# 변환 대상 확장자 정의
extensions = {".pdf", ".docx", ".pptx", ".xlsx", ".html", ".csv", ".json"}

success_count = 0
fail_count = 0

for file in input_dir.iterdir():
    if file.suffix.lower() in extensions:
        try:
            result = md.convert(str(file))
            output_path = output_dir / f"{file.stem}.md"
            output_path.write_text(result.text_content, encoding="utf-8")
            print(f"[v] Converted: {file.name}")
            success_count += 1
        except Exception as e:
            print(f"[!] Error converting {file.name}: {e}")
            fail_count += 1

print(f"\n--- Results ---")
print(f"Success: {success_count}, Failed: {fail_count}")

sequenceDiagram
    participant User as 사용자 코드
    participant MD as MarkItDown
    participant Parser as 내부 파서
    participant LLM as LLM Client

    User->>MD: MarkItDown(llm_client, llm_model)
    User->>MD: md.convert("file.pptx")
    MD->>MD: 파일 확장자 감지 (.pptx)
    MD->>Parser: python-pptx 파서 선택
    Parser->>Parser: 슬라이드 텍스트 추출
    Parser->>Parser: 이미지 발견
    Parser->>LLM: 이미지 캡셔닝 요청
    LLM-->>Parser: 이미지 설명 텍스트 반환
    Parser-->>MD: 마크다운 텍스트 생성
    MD-->>User: result.text_content

9. 애플리케이션과의 통합   |   MCP 서버와 Docker

MarkItDown을 단순히 CLI 도구나 Python 라이브러리로 사용하는 것을 넘어서, AI 에이전트의 "도구(tool)"로 등록하면 훨씬 강력한 워크플로우를 구성할 수 있습니다. 이를 가능하게 하는 것이 MCP(Model Context Protocol) 서버입니다. MCP는 Anthropic이 만든 오픈 표준 프로토콜로, AI 에이전트가 외부 도구를 호출하는 방법을 정의합니다. MarkItDown의 MCP 서버를 설정하면, Claude Desktop 같은 AI 클라이언트가 사용자의 요청에 따라 문서를 실시간으로 변환하고 분석하는 것이 가능해집니다.

MCP 서버를 통해 Claude Desktop 같은 AI 클라이언트가 MarkItDown의 변환 기능을 네이티브 도구로 호출할 수 있습니다
MCP 서버를 통해 Claude Desktop 같은 AI 클라이언트가 MarkItDown의 변환 기능을 네이티브 도구로 호출할 수 있습니다

MCP 서버 개요

markitdown-mcp 패키지는 MarkItDown의 변환 기능을 MCP 도구로 노출하는 경량 서버입니다. 이 서버는 하나의 도구인 convert_to_markdown(uri)를 제공하며, URI로 지정된 파일을 마크다운으로 변환하여 반환합니다. 지원되는 URI 스킴은 http:, https:, file:, data:이며, 로컬 파일과 원격 파일 모두 변환할 수 있습니다. 전송 모드(transport)는 STDIO, Streamable HTTP, SSE 3가지를 지원합니다.

전송 모드 설명 주요 사용처
STDIO 표준 입출력을 통한 통신. 가장 간단한 설정 Claude Desktop, 로컬 AI 클라이언트
Streamable HTTP HTTP 엔드포인트를 통한 통신. REST API처럼 동작 웹 애플리케이션, 원격 에이전트
SSE (Server-Sent Events) 서버에서 클라이언트로 이벤트를 스트리밍 실시간 변환 모니터링

MCP 서버 설치 및 실행

# MCP 서버 패키지 설치
pip install markitdown-mcp

# Docker로 실행 (STDIO 모드)
docker build -t markitdown-mcp:latest .
docker run -it --rm markitdown-mcp:latest

Claude Desktop 연동 설정

Claude Desktop에서 MarkItDown MCP 서버를 사용하려면, 설정 파일에 서버 정보를 등록해야 합니다. 설정 파일의 위치는 운영체제에 따라 다릅니다. macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows에서는 %APPDATA%\Claude\claude_desktop_config.json 경로에 위치합니다.

STDIO 모드  |  가장 간단한 설정

{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp"
    }
  }
}

Docker 기반 설정  |  로컬 파일 접근이 필요한 경우

{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/home/user/data:/workdir",
        "markitdown-mcp:latest"
      ]
    }
  }
}

Docker로 실행할 때는 -v 옵션으로 로컬 디렉토리를 컨테이너에 마운트해야 합니다. 마운트하지 않으면 file: URI로 로컬 파일에 접근할 수 없습니다. 설정 파일을 저장한 후 Claude Desktop을 재시작하면 MCP 서버가 로드됩니다.

연동이 완료되면, Claude Desktop에서 다음과 같은 프롬프트를 사용할 수 있습니다.

/path/to/file/report.pdf 파일의 내용을 요약해 주세요.

Claude가 MCP 서버의 convert_to_markdown 도구를 호출하여 파일을 마크다운으로 변환한 뒤, 그 결과를 기반으로 요약을 생성합니다. 사용자가 직접 파일을 변환할 필요 없이, 자연어 프롬프트만으로 문서 분석이 가능해지는 것입니다.

보안 주의사항

MCP 서버를 운영할 때 반드시 알아야 할 보안 사항이 있습니다. markitdown-mcp 서버는 기본적으로 로컬 신뢰 에이전트(local trusted agents)와의 사용을 위해 설계되었습니다. Streamable HTTP나 SSE 모드에서 실행할 때, 서버는 기본적으로 localhost에만 바인딩되어 외부에서 접근할 수 없습니다. 하지만 서버 자체에 인증(authentication) 기능이 없으므로, 같은 머신의 다른 프로세스나 사용자가 서버에 접근하여 convert_to_markdown 도구를 통해 파일을 읽을 수 있습니다. 따라서 민감한 파일이 있는 환경에서는 접근 제어에 주의해야 하며, 외부 네트워크에 서버를 노출하는 것은 권장하지 않습니다.

 

10. LLM과의 통합  |  Claude Code, Codex, Gemini

MarkItDown의 진정한 가치는 LLM과 결합했을 때 발휘됩니다. 문서를 마크다운으로 변환하는 것은 수단이고, 그 변환된 텍스트를 LLM이 분석, 요약, 질의응답하는 것이 최종 목적이기 때문입니다. 이 장에서는 현재 가장 널리 사용되는 AI 코딩 에이전트 및 LLM 플랫폼인 Claude Code, OpenAI Codex, Google Gemini에서 MarkItDown을 활용하는 방법을 소개합니다.

Claude Code에서의 활용

Claude Code는 Anthropic의 터미널 기반 AI 코딩 에이전트로, 코드베이스를 이해하고 자연어 지시에 따라 코드를 작성, 수정, 리팩토링하는 도구입니다. Claude Code에서 MarkItDown을 활용하는 방법은 두 가지가 있습니다. 첫째는 MCP 서버를 통한 연동이고, 둘째는 Claude Code 스킬(skill)로 설치하는 방법입니다.

방법 1  |  MCP 서버 연동

Claude Code의 MCP 설정 파일에 MarkItDown 서버를 등록하면, Claude Code가 자연어 명령에 따라 문서를 자동으로 변환하고 분석할 수 있습니다. 이 설정은 9장에서 다룬 Claude Desktop 설정과 동일한 방식입니다.

방법 2  |  Claude Code 스킬 설치

FastMCP 디렉토리에서 MarkItDown 스킬을 다운로드하여 프로젝트에 설치할 수 있습니다. 이 스킬은 MarkItDown의 변환 기능을 Claude Code의 작업 컨텍스트에 통합합니다.

# Claude Code 스킬 설치
mkdir -p .claude/skills/markitdown && \
  curl -L -o skill.zip "https://mcp.directory/api/skills/download/17" && \
  unzip -o skill.zip -d .claude/skills/markitdown && \
  rm skill.zip

스킬이 설치된 후, Claude Code에서 다음과 같은 명령을 내릴 수 있습니다.

이 프로젝트의 docs/ 폴더에 있는 모든 PDF를 마크다운으로 변환하고,
각 문서의 핵심 내용을 3줄로 요약해 주세요.

OpenAI Codex(CLI)에서의 활용

OpenAI의 Codex CLI는 터미널에서 자연어로 코드를 생성하고 실행하는 도구입니다. MarkItDown과 Codex를 조합하면, 문서 변환을 포함한 복잡한 데이터 파이프라인을 자연어로 구성할 수 있습니다. Codex는 OpenAI 호환 API를 지원하므로, MarkItDown의 Python API를 Codex 워크플로우 내에서 직접 호출하는 코드를 생성하도록 지시할 수 있습니다.

# Codex가 생성할 수 있는 워크플로우 예시
from markitdown import MarkItDown
from openai import OpenAI

# 1단계: 문서를 마크다운으로 변환
md = MarkItDown()
result = md.convert("quarterly_report.pdf")
markdown_text = result.text_content

# 2단계: 변환된 마크다운을 LLM에 전달하여 분석
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a financial analyst."},
        {"role": "user", "content": f"다음 분기 보고서를 분석해 주세요:\n\n{markdown_text}"}
    ]
)
print(response.choices[0].message.content)

Google Gemini에서의 활용

Google Gemini(AI Studio 또는 Vertex AI)에서 MarkItDown을 활용하는 패턴은 "전처리 도구"로서의 활용입니다. MarkItDown으로 문서를 변환한 뒤, 변환된 마크다운 텍스트를 Gemini의 컨텍스트로 전달하여 분석하는 2단계 프로세스를 구성합니다. Gemini는 긴 컨텍스트 윈도우(context window)를 지원하므로, 대용량 문서를 한 번에 처리하는 데 유리합니다.

from markitdown import MarkItDown
import google.generativeai as genai

# 1단계: MarkItDown으로 문서 변환
md = MarkItDown()
result = md.convert("technical_manual.docx")

# 2단계: Gemini에 전달하여 분석
genai.configure(api_key="your-gemini-api-key")
model = genai.GenerativeModel("gemini-2.0-flash")

response = model.generate_content(
    f"다음 기술 매뉴얼을 요약하고 핵심 주의사항을 정리해 주세요:\n\n{result.text_content}"
)
print(response.text)

실전 통합 시나리오 3가지

위에서 설명한 LLM 통합 방법들을 실전 시나리오로 정리하면 다음과 같습니다. 이 시나리오들은 MarkItDown이 LLM 파이프라인에서 어떤 역할을 하는지를 구체적으로 보여줍니다.

 

시나리오 1: 계약서 분석

법무 팀에서 받은 계약서 PDF를 MarkItDown으로 변환하고, Claude에게 핵심 조항, 리스크 요소, 주의사항을 분석하도록 요청합니다. 마크다운으로 변환된 계약서에서는 조항 번호와 항목 구조가 보존되므로, LLM이 "제3조 제2항"처럼 구체적인 조항을 정확히 참조할 수 있습니다.

 

시나리오 2: 발표 자료 요약

100페이지짜리 PowerPoint 발표 자료를 MarkItDown으로 변환하고, Gemini에게 슬라이드별 핵심 메시지를 추출하여 1페이지 브리핑 문서로 만들도록 요청합니다. 슬라이드의 제목과 본문 텍스트가 구조적으로 구분되어 변환되므로, LLM이 슬라이드 단위로 내용을 파악할 수 있습니다.

 

시나리오 3: RAG 지식베이스 구축

사내의 기술 문서, 회의록, 매뉴얼 등 다양한 형식의 문서를 MarkItDown으로 일괄 변환한 뒤, 청킹하여 벡터 데이터베이스에 인덱싱합니다. 이렇게 구축된 지식베이스를 기반으로 사내 Q&A 챗봇을 운영하면, 직원들이 자연어로 사내 규정이나 기술 사양을 질문할 수 있습니다.

flowchart LR
    subgraph 시나리오1["시나리오 1: 계약서 분석"]
        A1["계약서.pdf"] --> B1["MarkItDown\n변환"]
        B1 --> C1["Claude\n핵심 조항 분석"]
    end

    subgraph 시나리오2["시나리오 2: 발표 자료 요약"]
        A2["발표자료.pptx"] --> B2["MarkItDown\n변환"]
        B2 --> C2["Gemini\n브리핑 문서 생성"]
    end

    subgraph 시나리오3["시나리오 3: RAG 지식베이스"]
        A3["다양한 문서\nDOCX/PDF/XLSX"] --> B3["MarkItDown\n일괄 변환"]
        B3 --> C3["청킹 +\n벡터 인덱싱"]
        C3 --> D3["사내 Q&A\n챗봇"]
    end

    style B1 fill:#4A90D9,stroke:#333,color:#fff
    style B2 fill:#4A90D9,stroke:#333,color:#fff
    style B3 fill:#4A90D9,stroke:#333,color:#fff

11. Local LLM과의 통합   |  Qwen3, Gemma3, Ollama

클라우드 API를 사용한 LLM 통합은 편리하지만, 모든 상황에 적합한 것은 아닙니다. 사내 기밀 문서, 개인 의료 기록, 법률 서류 같은 민감한 문서를 외부 서버로 전송하는 것이 불가능한 경우가 있으며, 대량의 문서를 반복적으로 처리할 때 API 비용이 빠르게 누적되는 문제도 있습니다. 이런 상황에서는 Local LLM(로컬에서 구동하는 대규모 언어 모델)을 활용하여 데이터를 외부로 보내지 않는 완전히 독립적인 파이프라인을 구축할 수 있습니다. 이 장에서는 Ollama와 llama.cpp를 활용하여 MarkItDown과 Local LLM을 연동하는 방법을 단계별로 안내합니다.

완전한 로컬 RAG 아키텍처
완전한 로컬 RAG 아키텍처

Local LLM을 선택하는 이유

Local LLM을 선택하는 데는 세 가지 핵심적인 이유가 있습니다.

  • 첫째, 데이터 프라이버시입니다. 민감한 문서(인사 자료, 계약서, 의료 기록 등)를 처리할 때, 문서 내용이 외부 API 서버를 거치지 않으므로 데이터 유출 위험이 원천적으로 차단됩니다.
  • 둘째, 비용 절감입니다. 수천 개의 파일을 반복적으로 변환하고 분석해야 하는 RAG 파이프라인에서, API 호출 비용은 빠르게 누적됩니다. Local LLM은 초기 하드웨어 투자 이후에는 추가 비용 없이 무제한으로 사용할 수 있습니다.
  • 셋째, 오프라인 환경 지원입니다. 인터넷 연결이 불안정하거나 완전히 차단된 환경(보안 시설, 현장 작업 등)에서도 LLM 기반 문서 분석을 수행할 수 있습니다.

Ollama를 활용한 연동

Ollama는 Local LLM을 가장 쉽게 설치하고 실행할 수 있는 도구입니다. macOS, Linux, Windows를 모두 지원하며, 한 줄의 명령어로 모델을 다운로드하고 서빙할 수 있습니다. 특히 Ollama는 OpenAI 호환 API 엔드포인트를 기본 제공하므로, MarkItDown의 llm_client 파라미터와 바로 연동할 수 있습니다.

# 1단계: Ollama 설치 (Linux)
curl -fsSL https://ollama.com/install.sh | sh

# 2단계: Ollama 서버 시작
ollama serve

# 3단계: 비전 모델 다운로드 (이미지 OCR용)
ollama pull llava        # 또는 다른 비전 모델
ollama pull qwen3        # 텍스트 분석용

Ollama가 실행되면 http://localhost:11434에 OpenAI 호환 API 엔드포인트가 자동으로 생성됩니다. 이 엔드포인트를 MarkItDown의 llm_client로 연결하는 Python 코드는 다음과 같습니다.

from markitdown import MarkItDown
from openai import OpenAI

# Ollama의 OpenAI 호환 엔드포인트에 연결
client = OpenAI(
    api_key="ollama",                       # Ollama는 API 키 불필요 (아무 값이나 입력)
    base_url="http://localhost:11434/v1"     # Ollama의 OpenAI 호환 엔드포인트
)

# Local LLM을 연동한 MarkItDown
md = MarkItDown(
    llm_client=client,
    llm_model="llava",       # Ollama에서 다운로드한 비전 모델
    llm_prompt="이 이미지의 내용을 상세히 설명해 주세요"
)

# 이미지 파일에서 OCR/캡셔닝 (외부 API 호출 없이 완전 로컬 처리)
result = md.convert("scanned_document.png")
print(result.text_content)

이 코드의 핵심은 base_url을 Ollama의 로컬 엔드포인트로 지정하는 것입니다. MarkItDown은 내부적으로 OpenAI 호환 API를 호출하므로, 엔드포인트만 바꾸면 OpenAI 대신 Ollama(Local LLM)를 사용할 수 있습니다. 이 원리는 Ollama뿐 아니라 OpenAI 호환 API를 제공하는 모든 서비스(llama.cpp, vLLM, LM Studio 등)에 동일하게 적용됩니다.

llama.cpp를 활용한 고급 설정

더 세밀한 성능 제어가 필요하거나, Ollama가 지원하지 않는 모델을 사용하고 싶다면 llama.cpp의 llama-server를 직접 구동할 수 있습니다. llama.cpp는 다양한 GGUF 양자화 모델을 효율적으로 서빙하며, GPU 가속을 완전히 제어할 수 있습니다.

# llama.cpp 빌드
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build \
  -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON    # GPU 사용 시
cmake --build llama.cpp/build --config Release -j \
  --clean-first --target llama-server

# Qwen3.5-35B 모델 서빙 (OpenAI 호환 API)
./llama.cpp/build/bin/llama-server \
  -hf Qwen/Qwen3.5-35B-A3B-Instruct-GGUF:Q4_K_M \
  --port 8001 \
  -c 32768 \
  --jinja

llama-server가 실행되면, MarkItDown에서 동일한 패턴으로 연결합니다.

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI(
    api_key="sk-no-key-required",
    base_url="http://localhost:8001/v1"
)

md = MarkItDown(llm_client=client, llm_model="qwen3.5")
result = md.convert("technical_spec.pdf")
print(result.text_content)

완전 로컬 RAG 파이프라인 구성

MarkItDown과 Local LLM을 결합하면, 데이터가 외부로 전혀 나가지 않는 완전 로컬 RAG(Retrieval-Augmented Generation) 파이프라인을 구축할 수 있습니다. 전체 파이프라인은 다음과 같이 구성됩니다. 문서를 MarkItDown으로 마크다운으로 변환하고, 청킹(적절한 크기로 분할)한 뒤, Ollama의 임베딩 모델(nomic-embed-text)로 벡터화하여 ChromaDB에 저장합니다. 사용자가 질문하면, 질문을 벡터화하여 가장 관련 있는 청크를 검색하고, Local LLM(Qwen3, Gemma3 등)에게 검색된 컨텍스트와 함께 질문을 전달하여 답변을 생성합니다.

# 완전 로컬 RAG 파이프라인 핵심 코드 (개념 예시)
from markitdown import MarkItDown
from openai import OpenAI
import chromadb

# 1단계: 문서 변환
md = MarkItDown()
result = md.convert("company_manual.docx")
markdown_text = result.text_content

# 2단계: 청킹 (마크다운 헤딩 기반 분할)
chunks = markdown_text.split("\n## ")  # 간단한 헤딩 기반 청킹

# 3단계: 임베딩 및 벡터 DB 저장
chroma_client = chromadb.Client()
collection = chroma_client.create_collection("company_docs")

# Ollama의 임베딩 모델 사용
embed_client = OpenAI(
    api_key="ollama",
    base_url="http://localhost:11434/v1"
)

for i, chunk in enumerate(chunks):
    response = embed_client.embeddings.create(
        model="nomic-embed-text",
        input=chunk
    )
    collection.add(
        ids=[f"chunk_{i}"],
        documents=[chunk],
        embeddings=[response.data[0].embedding]
    )

# 4단계: 질의 및 답변 생성
query = "사내 휴가 신청 절차가 어떻게 되나요?"
query_embed = embed_client.embeddings.create(
    model="nomic-embed-text", input=query
).data[0].embedding

results = collection.query(query_embeddings=[query_embed], n_results=3)
context = "\n".join(results["documents"][0])

# Local LLM으로 답변 생성
llm_client = OpenAI(
    api_key="ollama",
    base_url="http://localhost:11434/v1"
)
response = llm_client.chat.completions.create(
    model="qwen3",
    messages=[
        {"role": "system", "content": f"다음 컨텍스트를 참고하여 답변하세요:\n{context}"},
        {"role": "user", "content": query}
    ]
)
print(response.choices[0].message.content)

Local LLM 모델별 추천 하드웨어

모델 파라미터 추천 GPU VRAM 추천 RAM 주요 용도
Qwen3-4B 4B 4GB+ 8GB+ 경량 텍스트 분석, 요약
Gemma3-9B 9B 8GB+ 16GB+ 범용 문서 분석
Qwen3.5-35B (MoE) 35B (3B 활성) 24GB+ 32GB+ 고품질 코딩/분석 작업
Qwen3-VL-30B 30B (3B 활성) 24GB+ 32GB+ 이미지 OCR, 비전 작업
Llava 7B~13B 8~16GB 16GB+ 이미지 캡셔닝/OCR

 

[i] 참고: Apple Silicon Mac에서는 통합 메모리(Unified Memory)를 활용할 수 있으므로, 별도 GPU 없이도 30B급 모델을 구동할 수 있습니다. M4 Pro 48GB 기준으로 Qwen3.5-35B를 쾌적하게 실행할 수 있습니다.

 

12. LLM 관점에서 MarkItDown의 역할

지금까지 MarkItDown의 기능과 사용법을 상세히 살펴보았습니다. 이 장에서는 한 발짝 뒤로 물러나, LLM 파이프라인이라는 큰 그림 속에서 MarkItDown이 어떤 위치를 차지하고 어떤 역할을 하는지를 조망합니다. 이 관점을 이해하면, MarkItDown을 단순한 파일 변환 도구가 아닌 AI 시스템의 핵심 인프라 구성 요소로 바라볼 수 있게 됩니다.

LLM 파이프라인에서의 위치

전형적인 LLM 애플리케이션 파이프라인은 다음과 같은 단계로 구성됩니다. 데이터 수집 -> 전처리 -> 청킹 -> 임베딩 -> 벡터 DB 저장 -> 검색 -> LLM 추론 -> 응답 생성. 이 파이프라인에서 MarkItDown은 "전처리(Preprocessing)" 단계에 해당합니다. 즉, 다양한 형식의 원본 문서를 LLM이 이해할 수 있는 구조화된 마크다운 텍스트로 변환하는 "브릿지(bridge)" 역할을 합니다. 문서가 저장된 "파일 세계"와 LLM이 동작하는 "AI 세계" 사이를 연결하는 번역기라고 이해하시면 됩니다.

 

이 전처리 단계의 품질이 전체 파이프라인의 성능을 좌우합니다. MarkItDown이 문서 구조를 정확하게 보존할수록, 이후의 청킹 단계에서 의미 있는 단위로 분할할 수 있고, 임베딩 품질이 향상되며, 최종적으로 LLM의 응답 정확도가 높아집니다. 반대로, 전처리 단계에서 표가 깨지거나 제목 구조가 손실되면, 아무리 좋은 LLM을 사용하더라도 정확한 답변을 기대하기 어렵습니다.

LLM 파이프라인내 역할
LLM 파이프라인내 역할

RAG에서의 시맨틱 청킹

마크다운으로 변환된 문서는 RAG 파이프라인의 청킹 단계에서 특별한 이점을 제공합니다. 일반적인 텍스트 청킹은 고정된 문자 수나 토큰 수를 기준으로 문서를 기계적으로 분할합니다. 하지만 이 방식은 문장이나 문단 중간에서 잘리는 문제가 발생합니다. 반면 마크다운 구조를 활용한 "시맨틱 청킹(semantic chunking)"은 헤딩(##, ###)을 기준으로 분할하므로, 각 청크가 하나의 완결된 주제를 담게 됩니다. 이렇게 의미 단위로 분할된 청크는 벡터 검색에서 더 높은 관련성(relevance) 점수를 받아, 사용자 질문에 대한 정확한 컨텍스트를 제공할 수 있습니다.

AI 에이전트의 도구로서

MarkItDown의 또 다른 중요한 역할은 AI 에이전트의 "문서 읽기 도구"입니다. AutoGen, LangChain, CrewAI 같은 에이전트 프레임워크에서는 에이전트가 외부 세계와 상호작용하기 위해 다양한 도구(tool)를 사용합니다. 웹 검색 도구, 코드 실행 도구, 데이터베이스 쿼리 도구 등이 대표적입니다. MarkItDown은 이런 도구 중 "문서 변환 및 읽기 도구"로 등록할 수 있으며, 특히 MCP 표준을 통해 에이전트-도구 간의 표준화된 인터페이스를 제공합니다. AI 에이전트가 "이 PDF 파일을 읽어서 3페이지의 내용을 요약해 줘"라는 지시를 받으면, MCP를 통해 MarkItDown을 호출하여 파일을 마크다운으로 변환하고, 그 결과를 분석하여 답변을 생성하는 것입니다.

래 전망

멀티모달 LLM(GPT-4o Vision, Claude의 이미지 분석 등)의 발전으로, 일부에서는 "이미지를 직접 LLM에 넣으면 되지 않느냐"는 의문을 제기할 수 있습니다. 그러나 마크다운 전처리는 여전히 중요한 의미를 가집니다.

  • 첫째, 대량 문서 처리에서 이미지 입력은 비용과 지연 시간이 텍스트보다 훨씬 크므로, 텍스트로 추출 가능한 내용은 마크다운으로 변환하는 것이 경제적입니다.
  • 둘째, 벡터 데이터베이스에 저장하려면 결국 텍스트 형태가 필요합니다.
  • 셋째, 플러그인 생태계가 확장되면서 MarkItDown의 처리 가능 범위가 지속적으로 넓어지고 있으며, 커뮤니티의 기여를 통해 새로운 파일 형식과 변환 전략이 계속 추가되고 있습니다.

13. 커뮤니티 활용 사례 및 워크플로우 자동화

MarkItDown은 오픈소스 생태계에서 이미 다양한 방식으로 활용되고 있습니다. 이 장에서는 실제 커뮤니티에서 보고된 활용 사례들과, n8n 같은 워크플로우 자동화 도구와의 통합 방법을 소개합니다.

n8n 워크플로우 자동화

n8n은 오픈소스 워크플로우 자동화 플랫폼으로, 400개 이상의 서비스를 시각적으로 연결하여 자동화 파이프라인을 구성할 수 있습니다. n8n 커뮤니티에서는 MarkItDown을 n8n 워크플로우에 통합할 수 있는 커뮤니티 노드인 @bitovi/n8n-nodes-markitdown을 개발하여 공개했습니다. 이 노드를 사용하면 n8n의 시각적 워크플로우 빌더에서 MarkItDown 변환을 하나의 노드로 추가할 수 있습니다.

n8n Docker 환경에 MarkItDown을 통합하려면, 아래와 같은 커스텀 Dockerfile을 사용합니다.

FROM n8nio/n8n:latest

USER root
RUN npm install -g pnpm

# Python과 MarkItDown 설치
RUN apk add --no-cache --virtual .build-deps \
    git build-base python3-dev py3-pip && \
  apk add --no-cache python3 && \
  pip install markitdown --break-system-packages && \
  apk del .build-deps

ENV PATH="/usr/local/bin:$PATH"

USER node
WORKDIR /home/node/.n8n/nodes

# n8n MarkItDown 노드 설치
RUN npm install @bitovi/n8n-nodes-markitdown

이 Docker 이미지를 빌드하고 실행하면, n8n 워크플로우에서 MarkItDown 노드를 사용할 수 있게 됩니다. 대표적인 워크플로우 시나리오는 다음과 같습니다.

워크플로우 예시  |  Google Drive 문서 자동 변환 및 AI 요약

이 워크플로우는 Google Drive에 새 파일이 업로드될 때마다 자동으로 실행됩니다. Google Drive 트리거 노드가 새 파일을 감지하면, 파일을 다운로드하고, MarkItDown 노드가 마크다운으로 변환한 뒤, AI 노드(Claude 또는 GPT)가 요약을 생성하고, 최종 결과를 Slack 채널로 전송합니다.

flowchart LR
    A["Google Drive\n트리거: 새 파일"] --> B["파일\n다운로드"]
    B --> C["MarkItDown\n마크다운 변환"]
    C --> D["AI 노드\n요약 생성"]
    D --> E["Slack\n결과 전송"]

    style C fill:#4A90D9,stroke:#333,color:#fff
    style D fill:#9B59B6,stroke:#333,color:#fff

AutoGen 멀티에이전트 시스템

MarkItDown은 Microsoft AutoGen 프레임워크에서 탄생했으므로, AutoGen과의 통합이 가장 자연스럽습니다. AutoGen의 멀티에이전트 시스템에서 MarkItDown은 "문서 읽기" 전담 에이전트의 핵심 도구로 활용됩니다. 예를 들어, GAIA 벤치마크에서 AI 에이전트가 "이 PDF에서 3번째 표의 합계를 구하라"는 과제를 수행할 때, MarkItDown이 PDF를 마크다운 테이블로 변환하고, 다른 에이전트가 그 테이블 데이터를 분석하는 방식으로 협업합니다.

Obsidian / 지식 관리 시스템 연동

Obsidian은 마크다운 기반의 노트 관리 도구로, 개인 지식 관리(PKM, Personal Knowledge Management)에 널리 사용됩니다. MarkItDown을 Obsidian과 결합하면, 기존에 Word나 PDF로 보관하던 문서들을 마크다운으로 변환하여 Obsidian 보관함(vault)에 자동으로 추가할 수 있습니다. 최근 Andrej Karpathy가 제안한 "LLM Wiki" 패턴은 이 접근법의 진화된 형태입니다. LLM이 원본 문서에서 지식을 추출하고, 구조화된 마크다운 위키 페이지로 정리하여 지식이 점진적으로 축적되는 시스템을 구축하는 것입니다. MarkItDown은 이 파이프라인의 첫 번째 단계인 "원본 문서 -> 마크다운 변환"을 담당합니다.

기업 문서 관리 활용

기업 환경에서 MarkItDown의 대표적인 활용 사례를 정리하면 다음과 같습니다.

시나리오 도구 조합 효과
사내 지식베이스 구축 MarkItDown + 벡터 DB + LLM 다양한 형식의 사내 문서를 통합 검색 가능한 지식베이스로 전환
레거시 문서 마이그레이션 MarkItDown + 정적 사이트 생성기 Word/HTML로 된 레거시 문서를 마크다운 기반 문서 사이트로 이관
자동 보고서 요약 MarkItDown + n8n + LLM 정기적으로 업로드되는 보고서를 자동 변환하고 핵심 요약을 생성
제품 정보 추출 MarkItDown + 데이터 파이프라인 제조사 Office 파일에서 제품 사양/설명을 추출하여 DB에 저장
이메일 아카이빙 MarkItDown (Outlook MSG) + 검색 엔진 이메일 메시지를 마크다운으로 변환하여 전문 검색 인덱싱

커뮤니티 플러그인 생태계

MarkItDown의 플러그인 시스템은 커뮤니티 기반 확장의 핵심입니다. GitHub에서 #markitdown-plugin 해시태그로 검색하면 커뮤니티가 만든 다양한 플러그인을 찾을 수 있습니다. 현재 공식적으로 제공되는 플러그인으로는 markitdown-ocr이 있으며, 이 플러그인은 LLM Vision을 활용하여 문서 내 이미지에서 텍스트를 추출합니다. 직접 플러그인을 개발하고 싶다면, 공식 리포지토리의 packages/markitdown-sample-plugin 디렉토리에 있는 샘플 코드를 참고하면 됩니다. 플러그인은 Python의 entry_points 메커니즘을 통해 등록되므로, 별도의 패키지로 배포하여 pip install로 간단히 설치할 수 있습니다.

마무리  |  정리 및 다음 단계

이 글에서는 Microsoft의 오픈소스 문서 변환 도구인 MarkItDown을 전방위적으로 살펴보았습니다. 마지막으로 핵심 내용을 요약하고, 다음 단계를 안내합니다.

핵심 요약

MarkItDown은 PDF, Word, Excel, PowerPoint, 이미지, 오디오 등 다양한 파일 형식을 LLM이 바로 처리할 수 있는 마크다운으로 변환하는 경량 Python 유틸리티입니다. Microsoft Research의 AutoGen 팀이 개발했으며, MIT 라이선스로 자유롭게 사용할 수 있습니다. 가장 빠른 처리 속도(180+ files/sec)와 가장 다양한 형식 지원(15+ 형식)이 강점이지만, PDF 변환 정확도(25%)는 Docling이나 Marker보다 낮습니다. 이 트레이드오프를 이해하고, 용도에 맞는 도구를 선택하거나 하이브리드 전략을 구사하는 것이 중요합니다.

도입 의사결정 가이드

상황 추천 도구 이유

상황 추천 도구 이유
빠르게 다양한 문서를 AI에 투입하고 싶다 MarkItDown 속도와 형식 범위가 최고
복잡한 PDF의 정확한 변환이 필수다 Docling + MarkItDown (폴백) AI 레이아웃 분석의 정확도
문서 형식 간 양방향 변환이 필요하다 Pandoc 유일한 양방향 변환기
민감 문서를 외부로 보낼 수 없다 MarkItDown + Ollama (Local LLM) 완전 로컬 파이프라인
AI 에이전트에 문서 읽기 기능을 주고 싶다 MarkItDown + MCP 서버 표준 MCP 프로토콜 지원
n8n으로 문서 처리 자동화를 구축하고 싶다 MarkItDown + n8n 커뮤니티 노드 시각적 워크플로우 구성

다음 학습 경로

이 글의 내용을 실습해 본 후, 다음 주제로 학습을 확장하시면 좋겠습니다.

  • 첫째, MCP 서버를 직접 구성하고 Claude Desktop에 연동하여 실시간 문서 분석 워크플로우를 체험해 보시기 바랍니다.
  • 둘째, Ollama와 ChromaDB를 활용한 완전 로컬 RAG 파이프라인을 구축하여, 사내 문서 Q&A 시스템의 프로토타입을 만들어 보시기 바랍니다.
  • 셋째, MarkItDown의 플러그인 개발에 도전하여, 자신의 업무에 특화된 파일 형식이나 변환 로직을 추가해 보시기 바랍니다.

참고 자료

저작자표시 비영리 변경금지 (새창열림)

'AI 코딩' 카테고리의 다른 글

Pi Coding Agent 가이드  (0) 2026.03.31
.claude 폴더 구조 분석  (0) 2026.03.30
cmux - AI 코딩 에이전트 시대의 새로운 터미널  (0) 2026.03.22
vLLM 완벽 가이드 - 대규모 언어 모델 서빙의 새로운 표준  (0) 2026.03.19
Scrapling 설치부터 쿠팡 스크래핑까지  (0) 2026.03.14

관련글

티스토리툴바