AI 기술의 발전으로 대규모 언어 모델(LLM)이 다양한 산업 분야에서 활용되고 있습니다. 하지만 이러한 AI 시스템에 다양한 형식의 문서 데이터를 효과적으로 공급하는 것은 여전히 도전 과제로 남아있습니다. 마이크로소프트가 최근 공개한 MarkItDown MCP는 이러한 문제를 해결하기 위한 혁신적인 도구로, PDF, Word, PowerPoint 등 다양한 형식의 문서를 구조화된 마크다운으로 변환해 AI 시스템과의 통합을 원활하게 해줍니다.
왜 마크다운이 중요한가?
마크다운(Markdown)은 단순한 텍스트 형식처럼 보이지만, AI와 LLM 시대에 중요한 의미를 갖습니다.
마크다운은 단순하면서도 구조화된 형식으로 LLM에 최적화되어 있습니다. (출처: dev.to)
마크다운과 LLM의 관계
- 토큰 효율성: 마크다운은 최소한의 마크업만 사용하여 문서 구조를 표현하므로, 토큰 소비가 적습니다. LLM에서는 토큰 수가 비용과 처리 속도에 직접적인 영향을 미치기 때문에 이는 큰 장점입니다.
- 훈련 데이터와의 연관성: GPT-4와 같은 최신 LLM은 대량의 마크다운 형식 텍스트로 훈련되었습니다. 이 모델들은 자연스럽게 마크다운 구문을 이해하고 생성할 수 있으며, 이는 마크다운이 이들 모델의 ‘모국어’와 같다는 의미입니다.
- 구조 보존: 일반 텍스트 추출과 달리, 마크다운은 제목, 목록, 표, 링크 등의 문서 구조를 유지합니다. 이러한 구조는 LLM이 텍스트를 더 정확하게 이해하고 처리하는 데 중요한 맥락을 제공합니다.
- RAG 시스템 최적화: 검색 증강 생성(Retrieval-Augmented Generation, RAG) 시스템에서 마크다운 형식은 검색 품질과 생성 결과의 정확성을 크게 향상시킵니다.
MarkItDown이란?
MarkItDown은 마이크로소프트가 개발한 경량 Python 유틸리티로, 다양한 파일 형식을 마크다운으로 변환하여 LLM 및 관련 텍스트 분석 파이프라인에서 활용할 수 있게 해줍니다. 이 도구는 단순히 텍스트 추출에 초점을 맞춘 다른 변환기와 달리, 문서의 중요한 구조(제목, 목록, 표, 링크 등)를 보존하는 것을 우선시합니다. 현재 PDF, PowerPoint, Word, Excel, 이미지(OCR 포함), 오디오(음성 전사), HTML, CSV, JSON 등 다양한 형식을 지원합니다.
MarkItDown은 명령줄 도구와 Python 라이브러리 두 가지 방식으로 사용할 수 있습니다. 명령줄에서는 간단한 명령으로 문서를 변환할 수 있습니다:
markitdown file.pdf > output.md
Python API를 통해서는 코드로 통합할 수 있습니다:
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("file.pdf")
특히 이미지 처리 기능은 외부 LLM(예: OpenAI GPT-4o)과 연동하여 이미지 내용에 대한 상세한 설명을 생성할 수 있으며, 플러그인 시스템을 통해 확장 가능한 구조를 제공합니다. 이 기본 도구를 바탕으로 MarkItDown MCP는 이러한 변환 기능을 서버 기반 프로토콜로 확장하여 더 넓은 활용성을 제공합니다.
MarkItDown MCP란 무엇인가?
MarkItDown MCP(Model Context Protocol)는 마이크로소프트가 개발한 문서 변환을 위한 표준 방식을 제공하는 서버 기반 프로토콜입니다. 이는 Microsoft의 MarkItdown 라이브러리를 백엔드로 사용하며 RESTful API를 통해 문서 변환 서비스를 제공합니다.
MarkItDown MCP는 다양한 문서를 AI 친화적인 마크다운으로 변환합니다. (출처: dev.to)
핵심 기능
- 다양한 형식 지원: PDF, DOCX, PPTX 등 일반적인 문서 형식을 마크다운으로 변환합니다.
- 구조 보존: 고급 파싱 알고리즘을 통해 문서의 제목, 목록, 표 등 원본 구조를 유지합니다.
- 맞춤형 출력: 사용자가 최종 마크다운 스타일을 제어할 수 있는 설정을 제공합니다.
- 서버 운영: 자동화 시스템과 클라우드 설정에 통합할 수 있는 서버 프로세스로 실행됩니다.
MarkItDown MCP 서버 설정 및 사용하기
MarkItDown MCP를 활용하기 위해서는 먼저 서버를 설정해야 합니다. 서버는 STDIO 또는 SSE 모드로 실행할 수 있습니다.
설치
먼저 필요한 패키지를 설치합니다:
pip install markitdown-mcp
서버 실행
STDIO 모드 (기본)
STDIO 모드는 표준 입력 및 출력 스트림을 연결하며, 스크립트 기반 통합에 적합합니다:
markitdown-mcp
SSE 모드
SSE(Server-Sent Events) 모드는 웹 애플리케이션이나 장기 실행 연결에 적합합니다:
markitdown-mcp --sse --host 127.0.0.1 --port 3001
Docker를 사용한 실행
Docker를 사용하여 MarkItDown MCP를 실행할 수도 있습니다:
# Docker 이미지 빌드
docker build -t markitdown-mcp:latest .
# 실행
docker run -it --rm markitdown-mcp:latest
# 로컬 파일 접근을 위한 마운트
docker run -it --rm -v /home/user/data:/workdir markitdown-mcp:latest
기본 API 사용법
MarkItDown MCP는 convert_to_markdown(uri) 도구를 제공합니다. 여기서 uri는 http:, https:, file:, 또는 data: URI가 될 수 있습니다.
예를 들어, 다음과 같이 HTTP URL을 마크다운으로 변환할 수 있습니다:
{
"convert_to_markdown": {
"uri": "https://example.com/document.pdf"
}
}
또는 로컬 파일을 변환할 수도 있습니다:
{
"convert_to_markdown": {
"uri": "file:///workdir/document.pdf"
}
}
Claude Desktop에서의 MarkItDown MCP 활용 사례
MarkItDown MCP는 Claude Desktop과 같은 AI 애플리케이션에서 특히 유용하게 활용될 수 있습니다:
MarkItDown MCP를 Claude Desktop에 통합하면 다양한 문서 처리가 가능해집니다. (출처: dev.to)
Claude Desktop 연동 방법
Claude Desktop에서 MarkItDown MCP를 활용하려면 Docker 이미지를 사용하는 것이 권장됩니다. 다음과 같은 단계로 설정할 수 있습니다:
- Claude Desktop 설정 파일 액세스: Model Context Protocol 공식 문서의 지침에 따라
claude_desktop_config.json파일을 찾습니다. - 설정 파일 수정: 다음과 같은 JSON 항목을 추가합니다:
{
"mcpServers": {
"markitdown": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"markitdown-mcp:latest"
]
}
}
}
로컬 디렉토리를 마운트하려면 다음과 같이 설정할 수 있습니다:
{
"mcpServers": {
"markitdown": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v",
"/home/user/data:/workdir",
"markitdown-mcp:latest"
]
}
}
}
Claude Desktop에서의 활용 사례
- 문서 분석 및 요약: PDF, PowerPoint, Word 등 다양한 형식의 문서를 Claude에 업로드하여 마크다운으로 변환한 후 내용을 분석하고 요약할 수 있습니다.
- 지식 베이스 구축: 회사 내부 문서를 마크다운으로 변환하여 Claude와의 대화를 통해 정보를 검색하고 활용할 수 있습니다.
- 문서 변환 자동화: Claude에게 “이 PowerPoint를 마크다운으로 변환해줘”와 같은 간단한 명령만으로 변환 작업을 수행할 수 있습니다.
- 콘텐츠 리팩토링: 기존 문서를 마크다운으로 변환한 후, Claude의 도움을 받아 콘텐츠를 재구성하거나 개선할 수 있습니다.
LangChain을 활용한 마크다운 변환 예제
LangChain과 MarkItDown MCP 서버를 함께 사용하여 PDF 파일을 마크다운으로 변환하는 방법을 단계별로 살펴보겠습니다. 이 예제에서는 Groq의 LLaMA 모델을 사용합니다.
1단계: 필요한 라이브러리 가져오기
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from langchain_mcp_adapters.tools import load_mcp_tools
from langgraph.prebuilt import create_react_agent
import asyncio
from langchain_groq import ChatGroq
2단계: Groq LLM 초기화
# Groq 모델 초기화
model = ChatGroq(model="meta-llama/llama-4-scout-17b-16e-instruct", api_key="YOUR_API_KEY")
3단계: MCP 서버 구성
server_params = StdioServerParameters(
command="markitdown-mcp",
args=[] # STDIO 모드에는 추가 인수가 필요하지 않습니다
)
4단계: 비동기 변환 함수 정의
async def run_conversion(pdf_path: str):
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
print("MCP 세션이 초기화되었습니다.")
# 사용 가능한 도구 로드
tools = await load_mcp_tools(session)
print(f"로드된 도구: {[tool.name for tool in tools]}")
# ReAct 에이전트 생성
agent = create_react_agent(model, tools)
print("ReAct 에이전트가 생성되었습니다.")
# 파일 URI 준비 (로컬 경로를 file:// URI로 변환)
file_uri = f"file://{pdf_path}"
# 변환 요청으로 에이전트 호출
response = await agent.ainvoke({
"messages": [("user", f"Convert {file_uri} to markdown using Markitdown MCP just return the output from MCP server")]
})
# 마지막 메시지 내용 반환
return response["messages"][-1].content
5단계: 변환 함수 실행 및 결과 저장
if __name__ == "__main__":
pdf_path = "/path/to/your/document.pdf" # 절대 경로 사용
result = asyncio.run(run_conversion(pdf_path))
with open("output.md", 'w') as f:
f.write(result)
print("\n마크다운 변환 결과:")
print(result)
결론 및 전망
MarkItDown MCP는 문서 변환을 위한 강력하고 서버 기반의 방법을 제공합니다. 다양한 형식을 처리하고 구조화된 마크다운 출력을 생성하여 LLM과의 통합을 통한 문서 처리 작업의 자동화를 가능하게 합니다. 이는 문서화 관행을 확장 가능하게 지원하며, 테스트를 위한 서버를 사용하면 평가가 간단해집니다.
AI와 LLM 기술이 계속 발전함에 따라, MarkItDown MCP와 같은 도구는 다양한 데이터 소스를 활용하는 데 있어 더욱 중요해질 것입니다. 특히 기업 내부 문서, 레거시 데이터, 다양한 형식의 콘텐츠를 AI 시스템에 효과적으로 공급해야 하는 조직에게 이는 필수적인 도구가 될 것입니다.
마이크로소프트의 이 오픈소스 기여는 AI를 위한 데이터 준비라는 중요한 과제를 직접적으로 해결하며, 개발자들이 다양한 데이터 소스를 AI 애플리케이션에 활용하기 위한 장벽을 크게 낮추고 있습니다.
Comments