본문으로 건너뛰기
JournalTORIS / FIELD NOTES

← 블로그개발 도구

MarkItDown(microsoft/markitdown) — PDF·오피스 문서를 LLM용 마크다운·MCP로 바꾸는 법

Microsoft 오픈소스 MarkItDown의 지원 포맷, 선택형 설치, markitdown-ocr, markitdown-mcp 서버 연동 및 보안 가이드를 정리합니다.

#MarkItDown #Markdown #MCP #LLM #PDF #OpenSource

Read in English

MarkItDown(microsoft/markitdown) — PDF·오피스 문서를 LLM용 마크다운·MCP로 바꾸는 법

Q. PDF·PPT·엑셀 문서를 AI 에이전트에 넣기 전에 왜 굳이 마크다운으로 바꿔야 하나요? GPT-4o를 비롯한 주요 LLM은 마크다운 문법을 훈련 데이터에서 방대하게 학습해 제목·목록·표 구조를 정확히 읽습니다. 마이크로소프트의 오픈소스 MarkItDown은 PDF와 오피스 문서를 토큰 효율이 높은 마크다운으로 한 번에 정리해 RAG와 에이전트 파이프라인에 바로 넣을 수 있게 해 줍니다.

⚠️ 정확도 가드레일: 이 글은 2026년 11월 21일 기준 microsoft/markitdown 공식 GitHub 저장소(API·README)와 v0.1.9 릴리즈 노트(2026-10-21 발행)를 직접 확인해 작성했습니다. GitHub 별·포크 수와 지원 옵션은 이후 업데이트로 바뀔 수 있으며, Azure Document Intelligence·Content Understanding 및 이미지 캡셔닝·음성 전사 비용은 별도 과금 정책을 확인해야 합니다.

30초 요약

  • 압도적 생태계: Microsoft가 공개한 MIT 라이선스 Python 도구로, 2026년 11월 21일 기준 GitHub 별 197,251개, 포크 14,935개, 최신 버전 v0.1.9를 기록 중입니다.
  • 폭넓은 포맷 지원: PDF·PowerPoint·Word·Excel·HTML·CSV·JSON·XML·ZIP·EPub은 물론 이미지 EXIF·캡셔닝, 오디오 전사, YouTube 자막 URL까지 처리합니다.
  • 가벼운 로컬 기본기: 기본 변환기는 로컬 연산만 사용하며, 필요할 때만 [pdf, docx, pptx]처럼 원하는 의존성만 골라 설치할 수 있습니다.
  • MCP와 OCR 확장: markitdown-mcp 패키지로 Claude Desktop이나 Cursor에 convert_to_markdown(uri) 도구를 붙이고, markitdown-ocr 플러그인으로 이미지 속 텍스트도 뽑아냅니다.

MarkItDown 변환 파이프라인 구조도

왜 plain text 대신 MarkItDown인가

LLM 파이프라인에서 문서를 뽑을 때 가장 아까운 것은 깨진 표와 사라진 제목 위계입니다. 기존 textract 계열 도구가 글자만 줄줄이 긁어내는 데 집중했다면, MarkItDown은 제목(#), 목록(-), 표(|), 링크([text](url)) 같은 문서 골격을 최대한 살려 냅니다.

사람이 그대로 인쇄해 읽는 고해상도 레이아웃 복원이 목적은 아닙니다. 대신 AI 모델이 문맥을 오해하지 않고 적은 토큰으로 핵심을 파악하도록 최적화되어 있습니다. 웹 페이지를 AI용 마크다운으로 긁어오는 작업이 Firecrawl & Firecrawl Local의 영역이라면, 이미 내 컴퓨터와 사내 드라이브에 쌓여 있는 PDF·PPT·엑셀 문서를 정리하는 역할은 MarkItDown이 맡는 셈입니다.

MarkItDown 작업 환경 실사

광고

설치와 선택형 의존성 구조

Python 3.10 이상 3.14 이하 환경이라면 가상환경을 만든 뒤 한 줄로 설치할 수 있습니다. 전체 포맷을 다 쓰고 싶다면 [all] 옵션을, 서버 용량을 줄이고 싶다면 필요한 포맷 키만 괄호 안에 적으면 됩니다.

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

실무에서 자주 쓰는 선택형 의존성 키는 다음과 같습니다.

의존성 옵션 활성화되는 기능 비고
[all] 전체 선택 포맷 일괄 설치 로컬 테스트·개발용
[pdf, docx, pptx] PDF, Word, PowerPoint 문서 RAG 핵심 조합
[xlsx, xls] 최신 및 구형 Excel 시트 표 데이터 추출
[outlook] Outlook .msg 메일 파일 사내 아카이브 분석
[audio-transcription] .wav, .mp3 음성 전사 외부 호스트 서비스 연동
[youtube-transcription] YouTube 영상 자막 추출 URL 직접 입력 지원
[az-doc-intel] / [az-content-understanding] Azure 클라우드 레이아웃·멀티모달 분석 유료 Azure API 호출

CLI 사용법도 단순합니다. 터미널에서 리다이렉션(>)이나 -o 플래그, 혹은 파이프(|)로 바로 연결됩니다.

markitdown report.pdf -o report.md
cat report.pdf | markitdown

Python API, OCR 플러그인, Azure 확장

코드 안에서 문서를 다룰 때는 MarkItDown().convert() 호출 두 줄로 끝납니다. 여기에 이미지나 발표자료 설명이 필요하면 OpenAI() 같은 llm_client와 llm_model을 넘겨 비전 모델이 슬라이드와 사진 내용을 서술하게 할 수 있습니다.

from markitdown import MarkItDown

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

스캔된 PDF나 이미지가 많이 섞인 문서라면 서드파티 플러그인 markitdown-ocr이 유용합니다. MarkItDown은 기본 상태에서 보안상 플러그인을 꺼 두므로(--use-plugins 또는 enable_plugins=True), 명시적으로 켜고 llm_client를 함께 넘겨야 이미지 속 텍스트 OCR이 동작합니다.

로컬 파싱으로 한계가 있는 복잡한 다단 표, 스캔 문서, 혹은 **오디오·비디오 파일의 구조화 필드 추출(YAML front matter)**이 필요하다면 Azure 연동을 선택할 수 있습니다. 아래는 공식 문서 기준 세 가지 변환 모드의 차이입니다.

구분 기본 내장 변환기 Azure Document Intelligence Azure Content Understanding
문서 변환 방식 오프라인 포맷별 파싱 클라우드 레이아웃 분석 클라우드 멀티모달 분석
구조화 필드 추출 미지원 모델·쿼리 필드 기반 YAML 분석기 필드 기반 YAML
오디오·비디오 기본 오디오만 지원 미지원 오디오·비디오 모두 지원
비용 로컬 연산(무료) Azure API 종량 과금 Azure API 종량 과금

Microsoft MarkItDown 공식 GitHub 저장소

MCP 서버(markitdown-mcp)로 Claude·Cursor에 붙이기

에이전트가 내 파일이나 웹 문서를 직접 마크다운으로 읽어 오게 하려면 markitdown-mcp 패키지를 씁니다. 이 패키지는 STDIO, Streamable HTTP, SSE 세 가지 전송 방식을 지원하며, MCP 클라이언트에 convert_to_markdown(uri) 도구 하나를 노출합니다. URI는 http:, https:, file:, data:를 모두 받습니다.

pip install markitdown-mcp
# STDIO 기본 실행
markitdown-mcp
# Streamable HTTP / SSE 로컬 실행
markitdown-mcp --http --host 127.0.0.1 --port 3001

Claude Desktop에서는 로컬 파일 접근 권한을 격리하기 위해 Docker 컨테이너에 특정 폴더만 마운트(/workdir)해 연결하는 방식이 공식 권장됩니다.

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

보안 주의사항: 편한 만큼 권한 경계를 좁혀야 합니다

Q. convert() 함수나 markitdown-mcp를 그대로 사내 웹 서비스에 올려도 될까요? 절대 권장하지 않습니다. MarkItDown은 현재 프로세스 권한 그대로 파일 I/O와 네트워크 요청을 실행하며, markitdown-mcp 자체에는 인증 기능이 없습니다.

공식 보안 가이드라인은 가장 좁은 범위의 API를 쓰라고 명확히 적고 있습니다. 로컬 파일만 읽는 서버라면 범용 convert() 대신 convert_local()을 쓰고, 외부 URL을 다룰 때는 애플리케이션이 직접 URL 검증(사설 IP, 루프백, 링크-로컬, 클라우드 메타데이터 주소 차단)을 거친 뒤 convert_response()나 convert_stream()에 스트림만 넘겨야 합니다. 또한 이미지 캡셔닝과 음성 전사는 외부 웹 서비스를 호출하므로 완전한 오프라인 폐쇄망이 필요하다면 관련 선택 의존성을 빼고 설치해야 합니다.

토리스의 판단

웹 크롤링보다 사내 오피스 문서·PDF 정리가 급한 1인 개발자나 팀이라면 오늘 바로 도입할 가치가 있습니다. 특히 Claude Desktop이나 Cursor에서 매번 PDF를 통째로 붙여넣다 토큰 한도에 걸렸던 경험이 있다면 markitdown-mcp를 Docker로 띄워 두는 것만으로도 작업 속도가 크게 달라집니다.

반대로 웹페이지 렌더링(SPA 자바스크립트 실행)이나 사이트 전체 맵핑이 목적이라면 MarkItDown보다 Firecrawl Local 쪽이 훨씬 정확합니다. 두 도구를 역할별로 나누어 쓰면 웹과 로컬 문서를 모두 깔끔한 마크다운으로 통합할 수 있습니다. 토리스 스튜디오의 자동화·개발 문의는 서비스 안내에서 확인하실 수 있습니다.

출처

광고

YOUTUBE · TORIS STUDIO

토리스 영상 더 보기