가이드 개요Microsoft에서 만든 무료 오픈소스 MarkItDown으로 PDF·PPT·Word·Excel 등을 Markdown(.md) 파일로 변환하는 방법입니다.
Claude Code를 처음 쓰는 분도 따라 할 수 있도록 PowerShell 실행 단축키 → 설치 → 변환 테스트 → 복사용 프롬프트 → Skill 순서로 정리했습니다.
먼저 알아두세요: Markdown 변환이 모든 문서의 토큰을 자동으로 줄여주는 것은 아닙니다. 이미지, 도표, 복잡한 레이아웃은 변환 과정에서 일부 정보가 손실될 수 있습니다. 중요한 문서는 원본과 비교해 확인하세요.
01. MarkItDown이란?
Microsoft가 공개한 MarkItDown은 다양한 문서를 AI가 처리하기 편한 Markdown 텍스트로 변환하는 도구입니다.
주요 지원 형식
- PDF (
.pdf) - Word (
.docx) - PowerPoint (
.pptx) - Excel (
.xlsx) - HTML (
.html), CSV, JSON, XML - 일부 이미지·오디오 등 (추가 도구나 설정이 필요할 수 있음)
작동 흐름
원본 문서 → MarkItDown → Markdown(.md) → Claude Code에서 분석
Markdown은 제목·목록·표 등 핵심 구조를 간결하게 표현합니다. 따라서 일부 문서에서는 AI가 다루는 텍스트를 단순화할 수 있습니다. 단, 변환 전후 토큰 사용량은 문서와 처리 방식에 따라 달라집니다.
공식 GitHub: microsoft/markitdown
02. 설치 전 준비사항
- Claude Code를 실행할 수 있는 컴퓨터
- 지원되는 Python 설치 (이 가이드 기준: Python 3.10~3.14)
- 인터넷 연결
MarkItDown 자체는 무료 오픈소스입니다. Claude Code 요금제 또는 API 이용에는 별도 비용이 발생할 수 있습니다.
Windows에서 PowerShell 여는 방법
가장 쉬운 방법: Windows + R → powershell 입력 → Enter
방법 1. 단축키로 열기 (추천)
- 키보드의 Windows 키 + R을 동시에 누릅니다.
- 작은 실행 창이 열리면
powershell을 입력합니다. - Enter를 누르면 PowerShell이 열립니다.
방법 2. 빠른 메뉴
- Windows 키 + X를 동시에 누릅니다.
- 터미널 또는 Windows PowerShell을 선택합니다.
- 터미널이 열렸다면 PowerShell 탭인지 확인합니다.
방법 3. 시작 메뉴 검색
- Windows 키를 누릅니다.
PowerShell을 검색합니다.- Windows PowerShell을 클릭합니다.
일반적인 설치와 버전 확인에는 관리자 권한이 필요하지 않습니다.
Mac에서 터미널 여는 방법
- Command(⌘) + Space를 동시에 누릅니다.
터미널또는Terminal을 검색합니다.- Enter를 누릅니다.
Python 설치 확인
Windows PowerShell:
python --versionMac 터미널:
python3 --version버전이 표시되지 않으면 Python 공식 다운로드에서 설치하세요. 설치 후에는 터미널을 닫고 다시 실행합니다.
03. 가장 쉬운 설치 — Claude Code에 맡기기
터미널이 낯설다면 아래 프롬프트를 Claude Code에 그대로 붙여넣으세요.
복사용 설치 프롬프트
Microsoft에서 개발한 MarkItDown을
내 Claude Code 작업 환경에서 사용할 수 있도록
설치하고 설정해줘.
공식 GitHub:
https://github.com/microsoft/markitdown
작업 순서:
1. 현재 운영체제와 Python 설치 상태를 확인해.
2. MarkItDown의 공식 설치 방법을 확인해.
3. 기존 Python 환경에 영향을 주지 않도록
가능한 경우 별도 가상환경을 구성해.
4. MarkItDown을 설치하고 정상 실행되는지 확인해.
5. PDF, PPTX, DOCX, XLSX 등 주요 문서의
Markdown 변환 기능을 사용할 수 있게 해.
6. 테스트용 문서가 있다면 MD 파일로 변환해
실제 출력 내용을 확인해.
7. Claude Code에서 MarkItDown을 편리하게
활용할 수 있는 방법을 안내해.
주의사항:
- 기존 파일을 삭제하거나 덮어쓰지 마.
- API Key 또는 유료 서비스를 임의로 사용하지 마.
- 설치가 필요하면 먼저 무엇을 설치할지 설명해.
- 공식 문서를 기준으로 설정해.
- 설치 후 실제 변환 테스트까지 진행해.
마지막에는 설치 성공 여부와 사용 방법을
초보자도 이해할 수 있도록 한국어로 정리해줘.Claude Code가 명령어 실행 승인을 요청할 수 있습니다. 내용을 확인한 뒤 승인하세요. 설치 완료 메시지뿐 아니라 실제 변환 결과까지 확인하는 것이 중요합니다.
04. 직접 설치하는 방법
기존 Python 패키지와 충돌하지 않도록 별도 가상환경을 권장합니다.
Windows — PowerShell
(윈도우 아이콘클릭 > 검색 > powershell 입력)
작업할 폴더에서 실행:
python -m venv .venv가상환경 활성화:
.\.venv\Scripts\Activate.ps1설치:
python -m pip install "markitdown[all]"PowerShell에서 스크립트 실행 제한 오류가 발생하면 보안 정책을 임의로 바꾸지 말고 가상환경의 Python으로 직접 설치할 수 있습니다.
.\.venv\Scripts\python.exe -m pip install "markitdown[all]"Mac — Terminal
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "markitdown[all]"[all]은 여러 지원 파일 형식에 필요한 추가 패키지를 함께 설치하는 옵션입니다.
설치 확인
가상환경이 활성화된 터미널에서:
markitdown --help도움말이 나오면 명령어를 실행할 수 있는 상태입니다. 가상환경을 활성화하지 않았다면 markitdown 명령어를 찾지 못할 수 있습니다.
05. 문서를 Markdown으로 변환하기
원본 파일이 현재 작업 폴더에 있다고 가정합니다.
PDF → Markdown
markitdown sample.pdf -o sample.mdPPT → Markdown
markitdown presentation.pptx -o presentation.mdWord → Markdown
markitdown report.docx -o report.md생성된 .md 파일은 VS Code, Obsidian, 일반 텍스트 편집기 등에서 확인할 수 있습니다.
변환 후 검수: 원본과 비교하여 표, 수치, 이미지 설명, 문서 순서가 제대로 추출됐는지 확인하세요.
06. Claude Code 실전 프롬프트
① PDF 변환 후 핵심 요약
현재 폴더에 있는 report.pdf를
Microsoft MarkItDown으로 Markdown으로 변환해줘.
변환 파일은 report.md로 저장하고,
변환된 내용의 누락이나 오류를 먼저 확인해.
그다음 핵심 내용, 주요 수치,
실행해야 할 작업을 요약해줘.
원본에서 확인되지 않는 내용은
추측하지 말고 별도로 표시해.② 여러 문서 한 번에 정리
현재 폴더의 PDF, DOCX, PPTX 파일들을 확인하고
MarkItDown으로 Markdown 형식으로 변환해줘.
변환된 파일은 converted 폴더에
원본 이름을 유지해 저장해.
그다음 문서별 핵심 내용을 요약하고,
공통 내용과 서로 다른 내용을 정리해줘.
기존 원본 파일은 수정하지 마.③ AI 지식베이스 구축
현재 폴더의 자료들을 MarkItDown으로 변환해
AI가 참고할 수 있는 지식베이스를 만들어줘.
문서별 출처 파일명을 유지하고
제목, 핵심 내용, 참고할 수 있는 항목을 정리해.
중복 내용은 표시하되 원본 정보는 보존해.
완성된 파일은 knowledge 폴더에 저장해.07. MarkItDown과 Claude Code Skill의 차이
MarkItDown: 문서를 Markdown으로 바꾸는 실제 프로그램입니다.
Claude Code Skill: Claude에게 언제, 어떻게 MarkItDown을 사용할지 알려주는 작업 지침입니다.
따라서 MarkItDown만 설치해도 변환할 수 있으며 Skill은 선택사항입니다. Skill을 만들어도 실제 변환 도구가 설치되어 있어야 합니다.
프로젝트용 Skill 생성 프롬프트
현재 설치된 Microsoft MarkItDown을
Claude Code에서 반복적으로 활용할 수 있도록
프로젝트용 Skill을 만들어줘.
요구사항:
- .claude/skills/markitdown/SKILL.md 구성
- 문서 변환 요청 시 MarkItDown 활용
- 원본 문서 보존
- MD 변환 파일은 지정한 폴더에 저장
- 변환 실패 시 오류 원인 보고
- 변환 결과의 누락 가능성 안내
- 파일 유형에 따라 필요한 추가 설정 확인
- PDF와 이미지의 시각적 정보가 중요하면
텍스트 변환 결과만으로 판단하지 않기
기존 Skill이나 설정을 덮어쓰지 마.
현재 공식 Claude Code Skill 형식에 맞춰
파일을 만들고 실제 동작을 확인해줘.08. 이런 작업에 활용해보세요
- 업무 문서 분석: PDF·PPT·Word 보고서의 핵심 내용 추출·비교
- 마케팅 리서치: 제안서, 경쟁사 자료, 조사 보고서의 텍스트 분석
- AI 지식베이스: 자료를 Markdown으로 정리해 프로젝트 참고 문서로 보관
- 반복 업무: 여러 파일을 같은 형식으로 변환해 분류·요약
09. 자주 묻는 질문 (FAQ)
Q. 토큰이 무조건 줄어드나요?
아닙니다. 변환 후 텍스트 구조가 단순해질 수 있지만 실제 토큰 사용량은 문서와 처리 방식에 따라 다릅니다.
Q. 이미지와 그래프도 완벽히 분석하나요?
아닙니다. 이미지·도표·복잡한 레이아웃의 정보가 일부 손실될 수 있습니다. 중요한 시각 정보는 원본도 함께 확인하세요.
Q. 설치하면 모든 파일이 자동 변환되나요?
아닙니다. 직접 명령하거나 Claude Code에 요청해야 합니다. Skill을 설정하면 반복 작업을 편리하게 할 수 있습니다.
Q. 모두 무료인가요?
MarkItDown 자체는 무료 오픈소스입니다. Claude Code 이용이나 별도 AI API를 사용하면 비용이 발생할 수 있습니다.
Q. 원본 파일은 삭제되나요?
일반적인 변환 명령은 원본을 변경하지 않습니다. 다만 출력 파일명과 경로가 기존 파일과 겹치지 않도록 확인하세요.
10. 마무리 & 공식 자료
처음에는 문서 한 개를 변환해보고, 정상적으로 작동하면 여러 문서 분석이나 지식베이스 구축으로 확장해보세요.
최종 업데이트: 2026년 10월 15일
Microsoft 또는 Anthropic의 공식 배포 문서가 아닌 개인 학습용 안내 자료입니다.