Markdownify
Markdownify 는 Model Context Protocol (MCP) 서버로, 다양한 파일 형식과 웹 콘텐츠를 마크다운 형식으로 변환합니다. PDF, 이미지, 오디오 파일, 웹 페이지 등 다양한 콘텐츠를 쉽게 읽기 쉽고 공유할 수 있는 마크다운 텍스트로 변환하는 도구들을 제공합니다.
기능
파일 형식 변환
- 이미지
- 오디오 (전사 포함)
- DOCX
- XLSX
- PPTX
웹 콘텐츠 변환
- YouTube 영상 전사
- Bing 검색 결과
- 일반 웹 페이지
기존 마크다운 파일 가져오기
설치 및 실행
저장소 복제
이 저장소를 클론하세요
의존성 설치
preinstall 단계는 .venv 에 Python 가상 환경을 생성하고 markitdown[all] 을 설치합니다.
프로젝트 빌드
서버 시작
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=/data/in:/data/out bun start 와 같이 설정합니다.
기여를 환영합니다! Pull Request 를 제출해 주세요.
이 프로젝트는 MIT 라이선스를 따릅니다. 자세한 내용은 LICENSE 파일을 참조하세요.