MarkItDown — LLM을 위한 범용 파일→Markdown 변환 엔진

한 줄 요약: Microsoft MarkItDown은 PDF, Office 문서, 이미지, 오디오, 웹/CSV/JSON/XML/ZIP 등을 LLM과 텍스트 분석 파이프라인에 넣기 쉬운 Markdown으로 변환하는 경량 Python 유틸리티다.

 

분석 기준일은 2026-05-27이다.

본 리포트는 GitHub README, 패키지별 README, 릴리스 노트, PyPI 메타데이터, 핵심 소스 구조를 기준으로 작성했다.

저장소 본문에서 기능 설명용 스크린샷이나 공식 아키텍처 PNG/GIF는 확인되지 않아, 아래의 시각 자료는 저장소 문서와 코드 구조를 바탕으로 재구성한 분석 기반 다이어그램이다.

---

Quick Links

구분	링크
GitHub Repository	https://github.com/microsoft/markitdown
Official README	https://github.com/microsoft/markitdown#readme
PyPI	https://pypi.org/project/markitdown/
Releases	https://github.com/microsoft/markitdown/releases
Issues	https://github.com/microsoft/markitdown/issues
Discussions	https://github.com/microsoft/markitdown/discussions
MCP package	https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp
OCR plugin	https://github.com/microsoft/markitdown/tree/main/packages/markitdown-ocr
Sample plugin	https://github.com/microsoft/markitdown/tree/main/packages/markitdown-sample-plugin
공식 데모	저장소 기준 별도 데모 페이지 확인 안 됨
공식 논문	저장소 기준 별도 논문 확인 안 됨

---

Deep Search & Analysis 요약

MarkItDown의 핵심 목표는 “문서를 보기 좋게 재현하는 것”이 아니라 “LLM이 다루기 쉬운 텍스트 구조로 바꾸는 것”이다. Markdown은 제목, 목록, 표, 링크, 코드 블록 같은 구조를 간결하게 보존할 수 있고, HTML보다 토큰 사용량이 적기 때문에 RAG, 에이전트, 문서 분석 워크플로에 적합하다.

저장소는 단일 라이브러리라기보다 여러 패키지로 구성된다.

packages/
├─ markitdown/                  # 핵심 CLI/API와 변환기 모음
│  └─ src/markitdown/converters # PDF, PPTX, DOCX, XLSX, 이미지, 오디오, HTML, ZIP 등
├─ markitdown-mcp/              # 로컬 MCP 서버
├─ markitdown-ocr/              # LLM Vision 기반 OCR 플러그인
└─ markitdown-sample-plugin/    # 플러그인 개발 예제

Wiki는 별도 문서 저장소라기보다 메인 저장소로 리다이렉트되는 형태로 확인되었다.

Discussions에는 Visio/레거시 Office/HWP 같은 포맷 확장, 스캔 PDF 처리, PPTX/DOCX 이미지 보존, MCP 저장 방식, 플러그인 우선순위 등 실제 도입 과정에서 부딪히는 이슈가 다수 보인다.

Image & Asset Harvesting 결과

확인한 README와 패키지 문서에는 주로 상태 배지(badge)가 포함되어 있었고, 기능 UI 스크린샷, 실행 GIF, 공식 아키텍처 다이어그램은 메인 브랜치에서 확인되지 않았다.

따라서 본 리포트의 이미지는 원본 스크린샷이 아니라, 문서와 소스 구조를 바탕으로 작성한 다이어그램이다.

각 이미지는 설명하는 섹션 바로 아래에 배치했다.

---

Key Features

1. LLM 친화적 Markdown 변환

MarkItDown은 입력 문서의 시각적 레이아웃을 완벽히 복제하기보다, LLM이 이해하기 쉬운 텍스트 구조를 추출하는 데 초점을 둔다. PDF의 본문과 표, Word 문서의 단락, PowerPoint의 슬라이드 요소, Excel의 표 데이터, 이미지 메타데이터, 오디오 전사 등을 Markdown으로 정리한다.

2. 넓은 파일 형식 지원

README 기준으로 지원 범위는 PDF, PowerPoint, Word, Excel, 이미지, 오디오, HTML, CSV/JSON/XML, ZIP, YouTube URL, EPUB 등이다. 포맷별로 필요한 선택 의존성이 다르므로 운영 환경에서는 markitdown[all] 또는 필요한 extra만 골라 설치하는 전략이 필요하다.

그림 1. 지원 형식과 변환 경로 매트릭스 — MarkItDown의 입력 포맷을 텍스트, 표, 이미지, 오디오, 클라우드 분석, 압축 파일 계층으로 나누어 정리한 다이어그램이다.
실제 운영에서는 입력 파일 유형과 선택 의존성 설치 여부를 함께 점검해야 한다.

3. CLI, Python API, Docker, MCP까지 연결되는 사용 경로

단순 변환은 CLI로 처리하고, 애플리케이션 내부에서는 Python API로 호출할 수 있다.

에이전트 환경에서는 MCP 서버를 통해 로컬 파일 또는 URI를 Markdown으로 변환하는 도구처럼 사용할 수 있다.

Dockerfile도 제공되어 CLI 변환 환경을 컨테이너로 감쌀 수 있다.

그림 2. CLI/API/MCP 사용 흐름 — 동일한 변환 엔진이 CLI, Python API, Docker, MCP 서버에서 재사용되는 구조다. MCP는 에이전트에게 강력한 파일 접근 도구가 되므로 권한 경계가 특히 중요하다.

4. 변환기 레지스트리와 플러그인 아키텍처

핵심 설계는 DocumentConverter 인터페이스와 변환기 레지스트리다.

각 변환기는 accepts()로 입력을 처리할 수 있는지 판단하고, convert()로 Markdown 결과를 만든다.

변환기는 우선순위 기반으로 정렬되어 실행되며, 플러그인은 entry point를 통해 추가 변환기를 등록할 수 있다.

그림 3. 변환기 레지스트리와 우선순위 — 기본 변환기와 플러그인 변환기가 같은 레지스트리에 등록된다.
낮은 priority 값이 먼저 평가되므로 OCR 플러그인처럼 기본 변환기보다 앞서 개입하는 구조를 만들 수 있다.

5. 멀티모달 입력 처리

이미지 변환기는 EXIF 메타데이터를 추출하고, OpenAI 호환 vision 모델을 연결하면 이미지 설명을 Markdown에 추가할 수 있다.

오디오 변환기는 speech recognition 계열 의존성을 통해 음성을 텍스트로 전사한다.

OCR 플러그인은 PDF, DOCX, PPTX, XLSX 안에 포함된 이미지나 스캔 PDF를 LLM Vision으로 보강하는 용도다.

6. Azure Document Intelligence / Content Understanding 연동

로컬 파서만으로 부족한 복잡한 문서 구조는 Azure Document Intelligence 또는 Azure Content Understanding 연동 옵션을 통해 처리할 수 있다.

문서 구조, 표, 레이아웃이 중요한 엔터프라이즈 문서에서는 이 경로가 더 적합할 수 있다.

단, 외부 서비스 호출이므로 비용, 지연 시간, 데이터 반출 정책을 함께 검토해야 한다.

7. 보안 경계가 명확한 I/O 모델

README와 MCP 문서는 입력 파일을 현재 프로세스 권한으로 읽고, URI를 가져오며, 플러그인도 실행할 수 있다는 점을 경고한다.

신뢰할 수 없는 파일이나 URI를 처리할 때는 샌드박스, 최소 권한, 허용 경로/도메인 제한, 로그 추적이 필요하다.

---

Tech Stack

Core Package

항목	내용
Package	markitdown
확인 버전	0.1.6
Python	>=3.10
License	MIT
Build backend	Hatchling
CLI entry point	markitdown = "markitdown.__main__:main"
핵심 의존성	beautifulsoup4, requests, markdownify, magika~=0.6.1, charset-normalizer, defusedxml

Optional Dependencies

Extra	주요 의존성	용도
pptx	python-pptx	PowerPoint 변환
docx	mammoth~=1.11.0, lxml	Word 변환
xlsx	pandas, openpyxl	Excel XLSX 변환
xls	pandas, xlrd	구형 Excel 변환
pdf	pdfminer.six>=20251230, pdfplumber>=0.11.9	PDF 본문/표 추출
outlook	olefile	Outlook 메시지 처리
audio-transcription	pydub, SpeechRecognition	오디오 전사
youtube-transcription	youtube-transcript-api~=1.0.0	YouTube 자막 추출
az-doc-intel	azure-ai-documentintelligence, azure-identity	Azure Document Intelligence
az-content-understanding	azure-ai-contentunderstanding>=1.2.0b1, azure-identity	Azure Content Understanding

Companion Packages

Package	확인 버전	역할
markitdown-mcp	0.0.1a5	STDIO, Streamable HTTP, SSE 기반 MCP 서버
markitdown-ocr	0.1.0	LLM Vision 기반 OCR 플러그인
markitdown-sample-plugin	예제 패키지	커스텀 변환기 등록 템플릿

---

Architecture

그림 4. MarkItDown 아키텍처 흐름도 — 입력 소스가 StreamInfo와 MIME/확장자/charset 추론 단계를 거쳐 변환기 레지스트리로 전달되고, 최종적으로 Markdown 결과가 생성되는 흐름을 나타낸다.

 

MarkItDown의 내부 흐름은 다음과 같이 이해할 수 있다.

1. 사용자는 CLI, Python API, Docker, MCP 중 하나로 변환을 요청한다.
2. convert()는 입력 타입에 따라 local path, URI, HTTP response, binary stream을 분기한다.
3. convert_local(), convert_uri(), convert_response(), convert_stream()은 입력을 seek 가능한 stream으로 만들고 StreamInfo를 구성한다.
4. MIME 타입, 파일 확장자, charset, Magika 기반 판별, charset-normalizer 결과를 조합해 입력 파일의 성격을 추론한다.
5. 변환기 레지스트리는 priority 순서로 정렬되고, 각 변환기의 accepts()가 처리 가능 여부를 판단한다.
6. 선택된 변환기의 convert()가 Markdown을 생성한다.
7. 최종 결과는 DocumentConverterResult의 markdown 필드로 반환된다.

핵심 소스 구조

markitdown/
├─ __main__.py              # CLI argument parsing
├─ _markitdown.py           # 변환 오케스트레이션, 플러그인 로딩, 레지스트리
├─ _base_converter.py       # DocumentConverter, DocumentConverterResult
├─ _stream_info.py          # MIME/extension/charset 추론 정보
├─ _uri_utils.py            # URI/local path 판별 유틸
└─ converters/
   ├─ _pdf_converter.py
   ├─ _pptx_converter.py
   ├─ _docx_converter.py
   ├─ _xlsx_converter.py
   ├─ _image_converter.py
   ├─ _audio_converter.py
   ├─ _html_converter.py
   ├─ _zip_converter.py
   ├─ _youtube_converter.py
   ├─ _doc_intel_converter.py
   └─ _cu_converter.py

PDF 변환 경로

PDF 변환기는 pdfplumber를 활용해 표와 폼 필드 추출을 시도하고, pdfminer.six 계열 추출을 보조적으로 사용한다.

최근 릴리스에서는 PDF 페이지 처리 후 메모리를 해제하는 개선도 반영되었다.

다만 PDF는 원래 텍스트 순서와 시각 레이아웃이 분리되기 쉬운 포맷이므로, 복잡한 2단 편집, 다중 컬럼, 차트, 스캔 문서는 후처리나 OCR/클라우드 분석이 필요할 수 있다.

PPTX 변환 경로

PPTX 변환기는 슬라이드 내부의 텍스트, 표, 이미지, 차트, 노트 등을 읽고, 위치 정보를 이용해 대체로 상단-좌측 기준 순서를 맞춘다.

이미지에는 alt text나 LLM caption이 포함될 수 있고, 옵션에 따라 data URI를 유지할 수도 있다.

Image/OCR 변환 경로

이미지 변환기는 메타데이터와 선택적 vision caption을 결합한다.

markitdown-ocr 플러그인은 PDF/DOCX/PPTX/XLSX 내부 이미지에서 OCR 텍스트를 얻기 위해 기본 변환기보다 앞선 priority로 등록되는 구조다.

이 설계는 스캔 PDF나 도표가 많은 문서에서 유용하지만, LLM Vision API 비용과 개인정보 보호 문제가 함께 발생한다.

MCP 경로

markitdown-mcp는 로컬 신뢰 에이전트가 convert_to_markdown(uri) 형태로 파일 또는 URI를 Markdown화할 수 있게 한다.

기본적으로 로컬 개발 환경에 적합하며, 인증 없는 서버를 외부 네트워크에 바인딩하는 것은 권장되지 않는다.

---

Usage & Setup

1. 기본 설치

python -m venv .venv
source .venv/bin/activate
pip install "markitdown[all]"

 

필요한 포맷만 사용할 경우 extra를 좁혀 설치한다.

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

2. CLI 사용

markitdown path-to-file.pdf -o document.md
cat path-to-file.pdf | markitdown
markitdown https://example.com/document.html -o page.md

3. Python API 사용

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("report.xlsx")
print(result.markdown)

4. 이미지 설명용 LLM 연결

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)
result = md.convert("figure.jpg")
print(result.markdown)

5. OCR 플러그인 사용

pip install markitdown-ocr openai

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)
result = md.convert("document_with_images.pdf")
print(result.markdown)

6. Azure 기반 문서 분석

markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"
markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

7. Docker 사용

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

8. MCP 서버 사용

pip install markitdown-mcp
markitdown-mcp
markitdown-mcp --http --host 127.0.0.1 --port 3001

9. 플러그인 개발 최소 구조

[project.entry-points."markitdown.plugin"]
my_plugin = "my_markitdown_plugin"

플러그인 패키지에서는 register_converters()를 구현해 커스텀 DocumentConverter를 등록한다.

예를 들어 HWP, LIMS export, 전자연구노트, 사내 규정 문서처럼 특정 도메인에 특화된 포맷을 처리할 수 있다.

---

Community Signals: Discussions/Issues에서 보이는 수요

Discussions와 이슈 흐름을 보면 MarkItDown의 사용자는 단순 “파일 텍스트 추출기”보다 더 넓은 활용을 기대한다.

• 포맷 확장: Visio, HWP, Loop 문서, 레거시 Office 파일처럼 조직별로 남아 있는 문서 포맷을 지원하려는 요구가 있다.
• 이미지와 OCR: DOCX/PPTX/PDF 내부 이미지 설명, 이미지 export, 스캔 PDF 처리는 반복적으로 등장하는 주제다.
• Agent/MCP 운영: MCP 서버가 변환 결과를 어디에 저장해야 하는지, 로컬 파일 접근을 어떻게 제한해야 하는지 같은 운영 질문이 있다.
• 플러그인 우선순위: 기본 변환기와 플러그인이 같은 포맷을 처리할 때 어떤 변환기가 먼저 개입해야 하는지가 중요하다.

실무적으로는 저장소의 “지원 포맷” 목록만 보고 도입하기보다, 실제 조직 문서 샘플을 테스트 벡터로 만들어 변환 품질을 검증해야 한다.

---

Personal Insights: 의료 AI, Bioinformatics, Autonomous Agent 관점

그림 5. 의료 AI·Bioinformatics·Agent 활용 파이프라인 — MarkItDown을 전처리 계층으로 두고, 이후 도메인 정규화, 청킹, 임베딩, RAG, 검증 계층을 연결하는 구성을 나타낸다.

의료 AI 관점

의료 AI에서는 임상시험 계획서, 동의서, 규제 문서, 임상 가이드라인, 방사선/병리 보고서, 보험/청구 문서처럼 다양한 형식의 문서가 섞인다. MarkItDown은 이런 문서를 Markdown으로 통일해 RAG나 요약 파이프라인에 넣는 전처리 계층으로 유용하다.

 

다만 변환 결과를 곧바로 임상 판단 근거로 사용해서는 안 된다.

환자식별정보(PHI) 제거, 원문 페이지/파일 provenance, 표/수치 검증, OCR 오류 검출, 접근 권한 통제가 반드시 필요하다.

특히 PDF 표에서 단위, reference range, 약물 용량이 어긋나면 위험하므로, Markdown화 이후 별도 검증 레이어를 두는 것이 안전하다.

Bioinformatics 관점

Bioinformatics에서는 논문 PDF, supplementary data, 실험 프로토콜, Excel/CSV 데이터, 장비 로그, 내부 분석 보고서가 혼재한다.

MarkItDown은 이런 자료를 한 번 Markdown으로 정규화해 검색·요약·질의응답 계층으로 넘기는 데 적합하다.

 

하지만 생물정보학 문서에서는 단순 텍스트 추출만으로 충분하지 않다.

유전자명은 HGNC, RefSeq, Ensembl 등으로 정규화해야 하고, 질병명은 MeSH/DOID, 기능 주석은 GO, pathway는 Reactome/KEGG 등과 연결해야 한다.

따라서 MarkItDown은 “문서 구조화의 시작점”이지, 도메인 의미 정규화의 종착점은 아니다.

Autonomous Agent 관점

MCP 서버는 에이전트가 파일을 직접 읽고 Markdown으로 변환할 수 있게 해준다.

이는 연구 보조 에이전트, 사내 문서 질의응답 에이전트, 개발자 도구 에이전트에 유용하다.

예를 들어 에이전트가 “이 PDF에서 실험 조건을 찾아 요약하라”는 요청을 받으면, MCP를 통해 파일을 Markdown화하고 이후 검색/요약 단계를 수행할 수 있다.

 

반대로 MCP는 보안상 강한 도구다. 파일 시스템과 URI 접근을 현재 사용자 권한으로 수행할 수 있기 때문이다.

운영 환경에서는 localhost 바인딩, 컨테이너 격리, 허용 디렉터리 제한, 네트워크 egress 제한, tool-call 로그, 민감정보 필터링을 함께 설계해야 한다.

기술적 결론

MarkItDown은 RAG/Agent 시스템의 “문서 ingestion 계층”을 단순화한다.

그러나 retrieval ranking, chunking, embedding, provenance, evaluation, access control까지 해결하는 시스템은 아니다.

안정적인 제품화를 위해서는 다음 계층이 추가되어야 한다.

Raw files
  → MarkItDown conversion
  → metadata/provenance enrichment
  → domain normalization
  → chunking
  → embedding/indexing
  → retrieval/reranking
  → answer generation
  → citation/evaluation/audit

---

Limitations & Risks

1. 고충실도 문서 렌더러가 아니다. 복잡한 레이아웃, 다단 편집, 차트, 스캔 문서에서는 손실이 발생할 수 있다.
2. 지원 포맷은 optional dependency에 의존한다. markitdown[all]을 설치하지 않으면 특정 포맷 변환기가 동작하지 않을 수 있다.
3. LLM/OCR/클라우드 경로는 비용과 개인정보 리스크가 있다. 이미지 caption, OCR, Azure 분석은 외부 API 호출을 수반할 수 있다.
4. MCP는 로컬 신뢰 환경 중심으로 봐야 한다. 인증 없는 HTTP/SSE 서버를 외부에 노출하면 파일 접근 위험이 생긴다.
5. 메인 브랜치의 공식 시각 자산이 부족하다. 본 리포트의 다이어그램은 분석 기반 재구성이며, 공식 스크린샷이나 공식 아키텍처 문서가 아니다.

---

결론

MarkItDown은 “여러 문서 포맷을 Markdown이라는 공통 언어로 낮추는” 실용적인 오픈소스 도구다.

특히 LLM/RAG/Agent 워크플로에서는 입력 문서의 형식 다양성이 큰 병목이 되는데, MarkItDown은 이 병목을 비교적 단순한 API와 CLI로 해소한다.

 

가장 강한 장점은 범용성, 플러그인 확장성, MCP 연결성이다.

가장 큰 주의점은 보안과 변환 품질 검증이다.

의료 AI나 Bioinformatics처럼 정확도와 추적성이 중요한 영역에서는 MarkItDown을 전처리기로 사용하되, 원문 provenance, 검증 파이프라인, 도메인 정규화, 접근 제어를 반드시 결합해야 한다.

---

References

• Microsoft MarkItDown GitHub README: https://github.com/microsoft/markitdown
• MarkItDown PyPI: https://pypi.org/project/markitdown/
• MarkItDown Releases: https://github.com/microsoft/markitdown/releases
• Core package source tree: https://github.com/microsoft/markitdown/tree/main/packages/markitdown
• Converter source tree: https://github.com/microsoft/markitdown/tree/main/packages/markitdown/src/markitdown/converters
• MCP package README: https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp
• OCR plugin README: https://github.com/microsoft/markitdown/tree/main/packages/markitdown-ocr
• Sample plugin README: https://github.com/microsoft/markitdown/tree/main/packages/markitdown-sample-plugin
• Discussions: https://github.com/microsoft/markitdown/discussions
• C4 architecture diagram proposal PR: https://github.com/microsoft/markitdown/pull/1401