MarkItDown으로 PDF · 엑셀을 마크다운으로 바꿔 AI에 넣기

KAITABASE가 공식 문서와 원문을 직접 읽고 새로 쓴 가이드입니다.

이 가이드로 할 수 있는 것

MarkItDown은 PDF, 워드, 파워포인트, 엑셀, HTML 같은 파일을 마크다운 글로 바꾸는 파이썬 도구입니다. 공식 README는 이 도구의 목적을 "사람이 보기 좋은 변환"이 아니라 "LLM과 텍스트 분석 도구가 읽을 글"로 밝힙니다. 그래서 문서를 통째로 AI에 올리기 전에 글자만 남겨 두면, AI가 읽어야 할 분량이 줄고 표 · 제목 구조도 텍스트로 남습니다.

이 가이드는 2026-10-22에 Windows 11에서 직접 설치하고 실행한 결과를 그대로 옮겼습니다. 끝까지 따라 하면 다음 세 가지가 됩니다.

1. 내 컴퓨터에 MarkItDown을 따로 격리된 가상환경으로 설치합니다.
2. 엑셀 · PDF 파일을 마크다운으로 바꾸고 결과를 확인합니다.
3. MarkItDown을 MCP 서버로 띄워 Claude Code 같은 AI 도구가 직접 부르게 합니다.

빠른 시작

이미 Python 3.10 이상이 있다면 아래 네 줄이면 됩니다. Windows PowerShell 기준입니다.

1234python -m venv .venv
.\.venv\Scripts\python -m pip install "markitdown[pdf,docx,xlsx]"
.\.venv\Scripts\markitdown --version
.\.venv\Scripts\markitdown 보고서.xlsx -o 보고서.md

성공하면 버전 줄이 이렇게 나옵니다(2026-10-22 기준 최신 0.1.9).

markitdown 0.1.9

STEP 1. 파이썬 버전 확인하기

목표: MarkItDown이 요구하는 Python 3.10 ~ 3.14가 있는지 확인합니다. · 예상 시간: 1분

python --version

확인 Python 3.10.x 부터 Python 3.14.x 사이면 다음 단계로 갑니다. 이 가이드는 Python 3.14.3 에서 확인했습니다.

막히면 python 을 찾을 수 없다고 나오면 python.org에서 설치하고 터미널을 새로 엽니다. 3.9 이하라면 README가 정한 범위를 벗어나므로 새 버전을 설치합니다. 3.15 이상도 아직 범위 밖입니다(PyPI 표기 <3.15,>=3.10).

STEP 2. 전용 폴더와 가상환경 만들기

목표: 다른 파이썬 프로그램과 패키지가 섞이지 않게 MarkItDown 전용 공간을 만듭니다. · 예상 시간: 2분

README는 의존성 충돌을 피하려고 가상환경을 권합니다.

mkdir markitdown-work
cd markitdown-work
python -m venv .venv

macOS · Linux에서는 python3 -m venv .venv 후 source .venv/bin/activate 로 켭니다. Windows에서는 .\.venv\Scripts\Activate.ps1 로 켤 수 있습니다.

확인 폴더 안에 .venv 폴더가 생기고, 그 안에 Scripts(Windows) 또는 bin(macOS · Linux)이 있습니다.

막히면 PowerShell이 "스크립트를 실행할 수 없습니다"라며 Activate.ps1 을 막으면, 켜지 않고 .\.venv\Scripts\python, .\.venv\Scripts\markitdown 처럼 경로를 붙여 직접 부르면 됩니다. 이 가이드의 명령은 모두 이 방식이라 켜지 않아도 동작합니다.

되돌리기 이 폴더를 통째로 지우면 설치한 것이 모두 사라집니다. 시스템 파이썬에는 아무것도 남지 않습니다.

STEP 3. MarkItDown 설치하기

목표: 필요한 형식만 골라 설치합니다. · 예상 시간: 3분

README의 기본 설치는 모든 형식을 넣는 markitdown[all] 입니다. 오디오 · 유튜브 · Azure 기능이 필요 없다면 필요한 형식만 골라 설치하는 편이 가볍습니다.

.\.venv\Scripts\python -m pip install "markitdown[pdf,docx,xlsx]"
.\.venv\Scripts\markitdown --version

고를 수 있는 묶음(README 기준): [pdf] [docx] [pptx] [xlsx] [xls] [outlook] [audio-transcription] [youtube-transcription] [az-doc-intel] [az-content-understanding] [all]

확인 markitdown 0.1.9 처럼 버전이 나오면 설치된 것입니다.

막히면 나중에 .pptx 를 바꿀 때 변환이 안 되면 그 형식 묶음이 빠진 것입니다. pip install "markitdown[pptx]" 로 추가합니다. macOS의 zsh에서는 대괄호 때문에 따옴표를 꼭 붙입니다.

STEP 4. 엑셀 파일 변환하기

목표: 표가 마크다운 표로 바뀌는 것을 눈으로 확인합니다. · 예상 시간: 2분

시트 이름이 매출 이고 지역 · 매출 두 열이 있는 엑셀 파일로 시험했습니다.

.\.venv\Scripts\markitdown sample.xlsx -o sample.md

실제 결과(sample.md):

12345## 매출
| 지역 | 매출 |
| --- | --- |
| 서울 | 420 |
| 부산 | 180 |

시트 이름은 소제목으로, 표는 마크다운 표로 바뀝니다. 이 상태라면 AI에 붙여 넣어도 열 이름과 값이 어긋나지 않습니다.

확인 sample.md 를 메모장이나 VS Code로 열어 한글이 그대로 보이는지 봅니다.

막히면 터미널 화면에 한글이 깨져 보이면(특히 Git Bash) 출력 방식 문제입니다. 화면에 찍지 말고 -o 파일이름.md 로 저장해서 파일을 엽니다. 이 가이드에서도 Git Bash 화면에서는 깨졌고, -o 로 저장한 파일은 정상이었습니다. PowerShell 5.1의 > 는 설정에 따라 UTF-16 등 다른 인코딩으로 저장할 수 있으니 -o 를 쓰는 편이 안전합니다.

STEP 5. PDF 변환하고 결과 점검하기

목표: PDF 변환 결과에서 무엇이 남고 무엇이 빠지는지 확인합니다. · 예상 시간: 3분

제목 · 목록 · 표가 들어간 한 쪽짜리 PDF(31,993바이트)로 시험했습니다.

.\.venv\Scripts\markitdown sample.pdf -o sample_pdf.md

실제 결과(215바이트):

123456789101112131415163분기 영업 보고

이 문서는 MarkItDown 변환 시험용 예시입니다.

요약

신규 고객 12곳
재계약률 91%

지역별 매출

지역 매출(백만 원)

서울 420

부산 180

글자는 모두 남았지만, 이 PDF에서는 # 제목 표시와 표 구분선이 사라지고 표가 줄글로 풀렸습니다. 파일 크기는 약 150분의 1로 줄었습니다. 표가 중요한 문서라면 원본이 엑셀 · 워드일 때 그 파일을 바로 변환하는 편이 낫습니다.

확인 변환한 .md 에서 숫자와 고유명사를 원본 PDF와 두세 군데 대조합니다.

막히면 결과가 거의 비어 있다면 스캔한 이미지 PDF일 가능성이 큽니다. 기본 변환기는 이미지 속 글자를 읽지 않습니다. README는 이런 경우 markitdown-ocr 플러그인(LLM 비전 사용)이나 Azure Document Intelligence를 안내하지만, 둘 다 외부 API를 쓰므로 비용과 자료 반출을 먼저 확인해야 합니다.

STEP 6. MCP 서버로 띄워 AI 도구에 연결하기

목표: AI가 대화 중에 직접 파일을 마크다운으로 바꾸게 합니다. · 예상 시간: 5분

markitdown-mcp 패키지는 convert_to_markdown(uri) 도구 하나를 제공하는 MCP 서버입니다. uri 에는 http:, https:, file:, data: 주소를 넣습니다.

.\.venv\Scripts\python -m pip install markitdown-mcp
.\.venv\Scripts\markitdown-mcp --help

직접 실행해 확인한 내용입니다. 표준 입출력(STDIO) 방식으로 서버를 띄우고 MCP 규격대로 도구 목록을 요청하자 convert_to_markdown 하나가 나왔고, 엑셀 파일 주소를 넣자 STEP 4와 같은 표가 돌아왔습니다.

1234server: {'name': 'markitdown', 'version': ''}
tools: ['convert_to_markdown']
result: ## 매출
| 지역 | 매출 | ...

Claude Code에는 공식 MCP 문서의 STDIO 서버 추가 형식으로 등록합니다. -- 뒤에는 서버를 실행하는 명령을 그대로 씁니다. 아래 경로는 내 폴더 위치로 바꿉니다.

claude mcp add --transport stdio --scope project markitdown -- C:\work\markitdown-work\.venv\Scripts\markitdown-mcp.exe
claude mcp get markitdown

--scope project 를 붙이면 프로젝트 폴더의 .mcp.json 에 저장되어 팀과 공유할 수 있고, 붙이지 않으면 기본값인 local 범위(내 ~/.claude.json 안의 이 프로젝트 항목)에 저장됩니다. 공식 문서 기준(직접 실행 안 함): 이 등록 명령은 사용자 설정 파일을 바꾸므로 이 가이드에서는 실행하지 않았습니다.

확인 공식 문서에 따르면 등록에 성공하면 Added ... 줄이 나오고, claude mcp get markitdown 으로 연결 상태를 볼 수 있습니다. .mcp.json 으로 등록한 서버는 처음 claude 를 열 때 승인 창이 뜹니다.

막히면 승인 대기(Pending approval)로 남아 있으면 그 폴더에서 claude 를 한 번 실행해 승인합니다. Claude Desktop에 붙일 때는 README가 Docker 이미지 사용을 권합니다.

되돌리기 claude mcp remove markitdown --scope project 로 지웁니다. 공식 문서는 범위별로 --scope 를 맞춰 지우라고 안내합니다.

잘못 쓰는 예 · 바르게 쓰는 예

바로 쓰는 프롬프트 · 템플릿

변환한 마크다운을 AI에 넣을 때 붙이는 요청 예시입니다.

1234567아래는 PDF를 MarkItDown으로 바꾼 글입니다. 변환 과정에서 표가 줄글로 풀렸을 수 있습니다.
1) 표였던 부분을 찾아 마크다운 표로 다시 묶어 주세요.
2) 숫자는 바꾸지 말고, 확신이 없는 칸은 "?" 로 남겨 주세요.
3) 마지막에 원본과 대조해야 할 숫자 목록을 따로 적어 주세요.

---
(여기에 변환 결과 붙여 넣기)

MCP로 연결했다면 Claude Code에서 이렇게 부릅니다.

convert_to_markdown 도구로 file:///C:/work/docs/report.docx 를 마크다운으로 바꾼 뒤,
제목 구조만 목차로 보여 주세요. 본문은 아직 요약하지 마세요.

주의할 점

• 권한: README는 MarkItDown이 실행한 사용자의 권한으로 파일과 네트워크에 접근한다고 경고합니다. 남이 보낸 경로나 주소를 검증 없이 넣지 않습니다. 코드로 쓸 때는 로컬 파일만 다루면 convert() 대신 convert_local() 처럼 범위가 좁은 함수를 쓰라고 권합니다.
• MCP 서버 보안: markitdown-mcp 는 인증 기능이 없습니다. HTTP 방식으로 띄우면 같은 컴퓨터의 다른 프로그램도 접근할 수 있으므로, localhost 이외의 주소에 묶지 않습니다.
• 요금: 기본 변환은 내 컴퓨터에서만 돌아 비용이 없습니다. Azure Document Intelligence · Content Understanding, OCR 플러그인은 호출할 때마다 외부 API 요금이 듭니다.
• 자료 반출: 기본 변환은 파일을 외부로 보내지 않지만, 변환한 글을 AI 서비스에 붙여 넣는 순간 회사 보안 규정이 적용됩니다.
• 라이선스: 저장소는 MIT 라이선스입니다. 마이크로소프트 상표 · 로고는 상표 지침을 따라야 합니다.

공식 자료

• MarkItDown 저장소 README — https://github.com/microsoft/markitdown
• markitdown-mcp README — https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp
• PyPI markitdown — https://pypi.org/project/markitdown/
• Python 가상환경(venv) 공식 문서 — https://docs.python.org/3/library/venv.html
• Claude Code MCP 연결 문서 — https://code.claude.com/docs/en/mcp

더 보기

이 가이드는 KAITABASE가 공식 문서와 원문을 직접 읽고 실행해 본 뒤 새로 쓴 자료입니다. 같은 주제의 다른 글은 KAITABASE에서 이어서 볼 수 있습니다.

• 지식 · 검색 자료 모음 — https://kaitabase.vercel.app/?area=knowledge
• KAITABASE 전체 자료 — https://kaitabase.vercel.app