Markdownify

Markdownify 는 Model Context Protocol (MCP) 서버로, 다양한 파일 형식과 웹 콘텐츠를 마크다운 형식으로 변환합니다. PDF, 이미지, 오디오 파일, 웹 페이지 등 다양한 콘텐츠를 쉽게 읽기 쉽고 공유할 수 있는 마크다운 텍스트로 변환하는 도구들을 제공합니다.

기능

파일 형식 변환

• 이미지
• 오디오 (전사 포함)
• DOCX
• XLSX
• PPTX

웹 콘텐츠 변환

• YouTube 영상 전사
• Bing 검색 결과
• 일반 웹 페이지

기존 마크다운 파일 가져오기

설치 및 실행

저장소 복제

이 저장소를 클론하세요

의존성 설치

bun install

preinstall 단계는 .venv 에 Python 가상 환경을 생성하고 markitdown[all] 을 설치합니다.

프로젝트 빌드

bun run build

서버 시작

bun start

TypeScript 컴파일러를 감시 모드로 시작하려면 bun run dev 를 사용하세요. src/server.ts 를 수정하여 서버 동작을 커스터마이징할 수 있습니다.

src/tools.ts 에서 도구를 추가하거나 수정할 수 있습니다.

데스크톱 앱과 통합하기

앱의 서버 구성에 다음을 추가하세요:

{
"mcpServers": {
"markdownify": {
...

모든 경로는 합리적인 기본값으로 설정됩니다. 설치 레이아웃에 기본값이 맞지 않을 때만 오버라이드하세요.

변수	기본값	목적
MARKITDOWN_PATH	<project>/.venv/bin/markitdown, then markitdown on PATH	markitdown 실행 파일의 절대 경로. 시스템 전체에 markitdown 을 설치한 경우 (예: pipx install "markitdown[pdf]") 버그드 venv 대신 이 경로를 설정하세요.
REPOMIX_PATH	<project>/node_modules/.bin/repomix, then repomix on PATH	git-repo-to-markdown 에서 사용하는 repomix 실행 파일의 절대 경로.
MD_ALLOWED_PATHS	unset (unrestricted)	서버가 읽을 수 있는 디렉터리 목록 (POSIX: :, Windows: ;). 설정 시, 모든 파일 입력 도구 (pdf-to-markdown, get-markdown-file 등) 는 이 디렉터리 외의 경로는 거부합니다.
MD_SHARE_DIR	unset	MD_ALLOWED_PATHS 의Deprecated alias(단일 디렉터리). 후방 호환성을 위해 여전히 존중됩니다.

Docker 빌드 및 실행

docker build -t markdownify-mcp .
docker run --rm -i \
-v "$HOME/Documents:/data:ro" \
...

Docker MCP 카탈로그에 대한 주석 (mcp/markdownify)

• 서버가 읽을 수 있는 호스트 디렉터리들을 컨테이너에 마운트한 후, 컨테이너 경로를 도구로 전달하세요 (예: /data/foo.pdf, /Users/you/Documents/foo.pdf 아님).
• MD_ALLOWED_PATHS 를 마운트된 디렉터리의 콜론 구분 목록으로 설정하여 서버가 바인드 마운트에 맞는 읽기 경계를 강제하세요.
• 게시된 Docker 이미지는 markitdown[pdf] 만 설치합니다. 오디오 전사와 이미지 OCR (audio-to-markdown, image-to-markdown) 은 [all] extras 를 필요로 하며, 슬림 이미지에서는 실패할 것입니다. 전체 기능 세트는 로컬 설치 (bun install) 를 사용하세요.

도구 목록

• youtube-to-markdown: YouTube 영상을 마크다운으로 변환
• pdf-to-markdown: PDF 파일을 마크다운으로 변환
• bing-search-to-markdown: Bing 검색 결과를 마크다운으로 변환
• webpage-to-markdown: 웹 페이지를 마크다운으로 변환
• image-to-markdown: 메타데이터와 함께 이미지를 마크다운으로 변환
• audio-to-markdown: 전사와 함께 오디오 파일을 마크다운으로 변환
• docx-to-markdown: DOCX 파일을 마크다운으로 변환
• xlsx-to-markdown: XLSX 파일을 마크다운으로 변환
• pptx-to-markdown: PPTX 파일을 마크다운으로 변환
• get-markdown-file: 기존 마크다운 파일 가져오기. 파일 확장자는 다음을 끝내야 합니다: *.md, *.markdown.

OPTIONAL: set

MD_ALLOWED_PATHS

모든 파일 입력 도구를 디렉터리 목록으로 제한하기 위해, 예를 들어 MD_ALLOWED_PATHS=/data/in:/data/out bun start 와 같이 설정합니다.

기여를 환영합니다! Pull Request 를 제출해 주세요.

이 프로젝트는 MIT 라이선스를 따릅니다. 자세한 내용은 LICENSE 파일을 참조하세요.