오픈소스

MarkItDown 쓰는 법

Microsoft의 MarkItDown은 PDF·Office·이미지·오디오 등을 LLM이 읽기 쉬운 Markdown으로 바꾸는 Python 도구다. 검색·RAG·에이전트 파이프라인에 넣기 전에, 설치부터 CLI·Docker·MCP까지 실제로 도는 경로만 정리한다.

jaykim

15 9월 2026 • 7 min read

핵심 요약 (TL;DR)

MarkItDown은 Microsoft가 연 오픈소스 Python 유틸이다. PDF, PowerPoint, Word, Excel, 이미지, 오디오, HTML, CSV/JSON/XML, ZIP, YouTube URL, EPub 등을 Markdown으로 바꿔 LLM·텍스트 분석 파이프라인에 넣기 쉽게 만든다. 최신 공개 버전은 GitHub 릴리스·PyPI 기준 v0.1.7이고, Python 3.10 이상, 라이선스는 MIT다.

설치는 보통 pip install 'markitdown[all]' 한 줄이다. CLI로 파일을 넘기거나, Python API의 MarkItDown().convert(...)를 쓰고, 필요하면 Docker·markitdown-mcp로 에이전트에 붙인다. 사람용 고품질 변환기라기보다, 구조(제목·목록·표·링크)를 살린 LLM 입력용 변환기다.

할 수 있는 일

microsoft/markitdown GitHub 저장소 OG 카드 — microsoft/markitdown 저장소의 GitHub 소셜 카드. 출처: GitHub

공식 README가 적어 둔 변환 대상은 대략 이렇다.

문서: PDF, PowerPoint(.pptx), Word(.docx), Excel(.xlsx / 구형 .xls), EPub
미디어: 이미지(EXIF·OCR), 오디오(EXIF·음성 전사)
웹·텍스트: HTML, CSV·JSON·XML, YouTube URL
묶음: ZIP(안쪽 파일을 순회)

추가로 Azure Document Intelligence·Azure Content Understanding 엔드포인트를 붙이면 스캔 PDF·표·영상 등에서 클라우드 쪽 품질을 끌어올릴 수 있다. 플러그인(#markitdown-plugin)과 markitdown-ocr(LLM 비전 OCR)도 문서화돼 있다. 에이전트 쪽에서는 markitdown-mcp가 convert_to_markdown(uri) 한 도구를 노출한다.

Microsoft Research Magentic-UI 블로그 OG — Microsoft Research Magentic-UI 소개 글의 OG. FileSurfer 에이전트가 MarkItDown으로 파일을 Markdown으로 바꾼다고 적힌 맥락. 출처: Microsoft Research

필요한 것

Python 3.10+ (공식 Prerequisites). venv / uv / conda 중 하나 권장.
pip로 markitdown 패키지. 포맷을 넓게 쓰려면 extras [all].
(선택) Docker — README의 docker build / docker run 경로.
(선택) Azure Document Intelligence 또는 Content Understanding 엔드포인트.
(선택) 이미지 설명·OCR용 OpenAI 호환 llm_client.
(선택) 에이전트 연동용 markitdown-mcp.

이 글은 Ollama·vLLM 같은 추론 엔진 설치 안내가 아니다. MarkItDown은 파일을 Markdown 문자열로 바꾸는 쪽이다.

단계 1) 설치

가상환경을 만든 뒤(예: python -m venv .venv && source .venv/bin/activate), 공식 권장 설치는 다음과 같다.

pip install 'markitdown[all]'

소스에서 개발 설치하려면:

git clone [email protected]:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

포맷만 골라 깔 수도 있다. 예: PDF·DOCX·PPTX만.

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

공식 extras 이름: all, pptx, docx, xlsx, xls, pdf, outlook, az-doc-intel, az-content-understanding, audio-transcription, youtube-transcription.

단계 2) CLI로 변환

markitdown path-to-file.pdf > document.md
markitdown path-to-file.pdf -o document.md
cat path-to-file.pdf | markitdown

플러그인을 켠 경우:

markitdown --list-plugins
markitdown --use-plugins path-to-file.pdf

Azure Document Intelligence:

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"
# 또는
export MARKITDOWN_DOCINTEL_ENDPOINT="<document_intelligence_endpoint>"
markitdown path-to-file.pdf -o document.md -d

Azure Content Understanding:

markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"
# 또는
export MARKITDOWN_CU_ENDPOINT="<content_understanding_endpoint>"
markitdown path-to-file.pdf --use-cu

단계 3) Python API

from markitdown import MarkItDown

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

이미지 설명(현재 README 기준 pptx·이미지)은 OpenAI 클라이언트를 넘긴다.

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI(max_retries=5)
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.markdown)

보안·권한 관점에서는 README가 convert()보다 좁은 API를 권한다. 로컬 파일만이면 convert_local(), 직접 받은 응답이면 convert_response(), 스트림이면 convert_stream().

단계 4) Docker

저장소 루트 Dockerfile 기준:

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

단계 5) MCP 서버(에이전트)

Microsoft 개발자 블로그 10 Microsoft MCP Servers OG — Microsoft 개발자 블로그 「10 Microsoft MCP Servers…」OG. MarkItDown MCP가 문서 변환 서버로 소개된 글. 출처: Microsoft Developer Blog

markitdown-mcp는 STDIO / Streamable HTTP / SSE로 MarkItDown을 감싼 MCP 서버다. 도구는 convert_to_markdown(uri) 하나이며, URI는 http:·https:·file:·data:를 받는다.

pip install markitdown-mcp
markitdown-mcp
# HTTP/SSE (기본 localhost)
markitdown-mcp --http --host 127.0.0.1 --port 3001

같은 Microsoft 글에 실린 VS Code Extensions 뷰의 MCP 서버 화면. 출처: Microsoft Developer Blog

공식 MCP README는 인증이 없고 실행 사용자 권한으로 돈다고 경고한다. HTTP/SSE는 기본이 localhost 바인딩이다. 다른 인터페이스에 붙이지 말라고 못 박혀 있다. Claude Desktop 예시는 Docker 이미지로 돌리는 구성을 권장한다.

막히는 지점 (표)

증상·질문	먼저 볼 것
특정 확장자가 안 됨	extras를 좁게 깔았는지. `[all]` 또는 `[pdf]`/`[docx]` 등 해당 extras.
스캔 PDF·복잡 표가 빈약	로컬 변환기 한계. Document Intelligence(`-d`) 또는 Content Understanding(`--use-cu`).
이미지 안 설명이 비어 있음	`llm_client`/`llm_model` 미설정. README는 pptx·이미지에 LLM 설명을 붙인다.
플러그인이 안 보임	기본은 비활성. `--list-plugins` 후 `--use-plugins`.
MCP로 로컬 파일 접근 실패(Docker)	볼륨 마운트. 예: `-v /home/user/data:/workdir` 후 컨테이너 경로로 URI.
서버를 0.0.0.0에 열고 싶음	공식 보안 문서: 인증 없음·파일 읽기 가능. localhost 유지가 기본 권장.
사람용 완벽한 PDF 복제 기대	목표가 다름. LLM 파이프라인용 구조 보존 Markdown.

공식 README 비교 한 줄: 내장 변환기는 오프라인·포맷별, Document Intelligence는 클라우드 레이아웃, Content Understanding은 멀티모달·YAML 필드 추출·영상까지. CU 호출은 Azure 과금이다. cu_file_types로 라우팅 범위를 줄일 수 있다.

보안 (짧게)

MarkItDown은 현재 프로세스 권한으로 I/O한다. open()·requests.get()과 같은 층이다. 신뢰할 수 없는 입력을 그대로 넘기지 말고, 경로·URI 스킴·사설/메타데이터 주소를 걸러라. 가능하면 convert_local()·convert_stream()처럼 좁은 API만 쓴다. MCP 서버도 같은 사용자 권한·무인증이므로 로컬 신뢰 에이전트용으로만 두는 편이 안전하다.

버전 확인

이 글을 확인할 때 GitHub 최신 릴리스 태그와 PyPI 버전은 모두 0.1.7(태그 v0.1.7)이었다. Python 요구는 >=3.10. 설치 후 pip show markitdown으로 맞는지 보면 된다.

마치며

MarkItDown 쓰는 법은 짧다. Python 3.10+에서 pip install 'markitdown[all]' → markitdown file.pdf -o out.md 또는 MarkItDown().convert(...). 에이전트에는 markitdown-mcp, 격리·재현에는 Docker. 스캔·영상·필드 추출이 필요하면 Azure 옵션을 켠다. MIT라서 파이프라인에 넣기 부담이 적다. 다만 권한과 입력 검증은 직접 책임져야 한다.

저장소: github.com/microsoft/markitdown · PyPI: markitdown · MCP: packages/markitdown-mcp

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.