/ 디렉터리 / 플레이그라운드 / MarkItDown MCP
● 공식 microsoft ⚡ 바로 사용

MarkItDown MCP

제작: microsoft · microsoft/markitdown

MCP로 제공되는 Microsoft의 MarkItDown — PDF, DOCX, PPTX, XLSX, 오디오, HTML을 Claude가 읽을 수 있는 깔끔한 Markdown으로 변환.

MarkItDown은 Microsoft의 범용 문서-to-Markdown 변환기로, MCP 서버로 패키징되었습니다. 오피스 문서, PDF, 이미지, 오디오 파일, ZIP, EPub, URL을 전달하면 Claude가 추론할 수 있는 구조화된 Markdown을 반환합니다. MCP 레이어(markitdown-mcp)는 같은 모노레포의 별도 패키지입니다.

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

markitdown-mcp.replay ▶ 준비됨
0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "markitdown-mcp": {
      "command": "uvx",
      "args": [
        "markitdown-mcp"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "markitdown-mcp": {
      "command": "uvx",
      "args": [
        "markitdown-mcp"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "markitdown-mcp": {
      "command": "uvx",
      "args": [
        "markitdown-mcp"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "markitdown-mcp": {
      "command": "uvx",
      "args": [
        "markitdown-mcp"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "markitdown-mcp",
      "command": "uvx",
      "args": [
        "markitdown-mcp"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json
{
  "context_servers": {
    "markitdown-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "markitdown-mcp"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add markitdown-mcp -- uvx markitdown-mcp

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: MarkItDown MCP

200페이지 PDF를 읽기 가능한 Markdown으로 Claude 앞에 놓기

👤 PDF 중심 워크플로우의 연구자, 법률가, 모든 사용자 ⏱ ~15 min beginner

언제 쓸까: PDF의 내용을 논의해야 하고 페이지를 복사-붙여넣기하고 싶지 않을 때.

흐름
  1. 변환
    Use markitdown. Convert ~/Downloads/whitepaper.pdf to Markdown. Tell me total length and section count.✓ 복사됨
    → TOC 요약과 함께 Markdown 반환
  2. 특정 내용 논의
    From section 3, what claims do they make about throughput? Quote the exact lines.✓ 복사됨
    → 섹션 참조와 함께 직접 인용
  3. 다른 문서와 비교
    Now convert competitor.pdf the same way. Compare their throughput claims.✓ 복사됨
    → 문서별 주장 표

결과: 두 PDF를 수집, 비교하고 채팅에서 인용 가능.

함정
  • 스캔된 PDF가 빈 내용으로 나옴 — MarkItDown은 기본 OCR을 수행 — 이미지 전용 PDF는 먼저 업스트림에서 OCR 실행
함께 쓰기: filesystem

브라우저 스크레이핑 없이 URL을 깔끔한 Markdown으로 변환

👤 URL로 기사나 문서를 수집하고 싶은 모든 사람 ⏱ ~10 min beginner

언제 쓸까: 기사가 동적으로 렌더링되거나 페이월 뒤에 있을 때; 원시 HTML이 아닌 구조화된 출력을 원할 때.

흐름
  1. 가져오기 및 변환
    Use markitdown to convert https://example.com/long-article. Strip nav and footer.✓ 복사됨
    → Markdown으로 변환된 기사 본문
  2. 요약 또는 인용
    Give me the core claim and the strongest evidence cited.✓ 복사됨
    → 구조화된 요약

결과: 추론 가능한 Markdown으로 변환된 URL.

함정
  • JS 중심 SPA에서 빈 내용 반환 — SPA에는 브라우저 기반 MCP(browser-act, mcp-chrome) 사용 후 markitdown으로 파이프

혼합된 오피스 문서 폴더를 지식 베이스로 일괄 변환

👤 내부 코퍼스를 구축하는 지식 운영, 지원 팀 ⏱ ~30 min intermediate

언제 쓸까: 혼합 문서가 있는 Dropbox/SharePoint 폴더를 모두 읽기 가능하게 만들고 싶을 때.

흐름
  1. 목록 확인
    List ~/docs/ — group by extension. How many PDFs, DOCXs, PPTXs?✓ 복사됨
    → 확장자별 개수
  2. 전체 변환
    Convert every doc in ~/docs/ to Markdown into ~/docs-md/. Preserve folder structure.✓ 복사됨
    → .md 파일이 있는 미러 트리
  3. 검색용 인덱스 생성
    Now give me a single index.md listing each doc's title and 2-line summary.✓ 복사됨
    → 지식 베이스 인덱스 파일

결과: 혼합 포맷 폴더가 균일한 Markdown 코퍼스로 변환.

함께 쓰기: filesystem

조합

다른 MCP와 조합해 10배 효율

markitdown-mcp + filesystem

소스 파일 읽기 후 일괄 변환

List ~/inbox/, convert each via markitdown, save to ~/processed/.✓ 복사됨
markitdown-mcp + office-word-mcp

Word 문서를 Markdown으로 변환하여 편집 후 다시 변환

MarkItDown the .docx → edit the .md → use word-mcp to write a new .docx with the edits.✓ 복사됨

도구

이 MCP가 노출하는 것

도구입력언제 호출비용
convert_to_markdown uri (file:// or http://) 텍스트로 원하는 모든 문서 0 (LLM hooks optional, paid)

비용 및 제한

운영 비용

API 쿼터
해당 없음 — 로컬
호출당 토큰
가변 — 대형 PDF는 수만 줄의 MD를 생성할 수 있음
금액
무료 (MIT). 선택적 LLM/Whisper 훅은 별도 청구.
큰 부록 건너뛰기 — 파일 유형에 맞게 SDK가 지원하는 경우 페이지 범위 변환

보안

권한, 시크릿, 파급범위

최소 스코프: filesystem-read outbound:url-fetch
자격 증명 저장: 기본적으로 없음; LLM 훅은 자체 키 필요
데이터 외부 송신: 가져오도록 지정한 URL; 훅 활성화 시 LLM 엔드포인트

문제 해결

자주 발생하는 오류와 해결

드문 포맷에서 ImportError

MarkItDown에는 선택적 extras가 있음: pip install markitdown[all]로 youtube/azure-docs 등 파서 포함

레거시 DOC에서 인코딩 오류

변환 전 Office에서 DOCX로 다시 저장; .doc 지원은 최선책

표가 찌그러져 보임

MarkItDown은 표 구조를 보존하지만 Claude는 명시적 프롬프트가 필요할 수 있음 — HTML 표 모드 요청

대안

MarkItDown MCP 다른 것과 비교

대안언제 쓰나단점/장점
Docling / Unstructured복잡한 과학 문서에서 PDF 레이아웃 충실도가 필요할 때더 무거운 의존성; 표에서 더 정확
kreuzberg스캔된 문서에서 OCR을 포함한 순수 텍스트 추출다른 최적화 대상

더 보기

리소스

📖 GitHub에서 공식 README 읽기

🐙 열린 이슈 보기

🔍 400+ MCP 서버 및 Skills 전체 보기