mcp-pandoc
- 추천0
- GitHub 별588
- 문서라이선스MIT
pandoc으로 문서 형식을 바꾸는 MCP 서버. Markdown · HTML · DOCX · PDF · PPTX · EPUB 등을 서식을 지킨 채 변환해요(uvx). MIT
설치 방법은 설치 탭에 정리했어요.
설명
mcp-pandoc: 문서 변환 MCP 서버
Model Context Protocol 서버 오픈소스 프로젝트에 공식으로 포함됐어요. 🎉
개요
pandoc으로 문서 형식을 바꾸는 Model Context Protocol 서버예요. 서식과 구조를 지킨 채 내용을 여러 문서 형식 사이에서 변환하는 도구를 제공해요.
mcp-pandoc은 아직 초기 개발 단계예요. PDF 지원은 개발 중이고, 서버를 계속 개선하면서 기능과 도구는 바뀌거나 늘어날 수 있어요.
감사의 말: 이 프로젝트는 문서 변환에 Pandoc Python 패키지를 쓰며, 그것이 프로젝트의 기반이에요.
📋 빠른 참조
mcp-pandoc이 처음이라면 **📖 CHEATSHEET.md**를 보세요.
- ⚡ 모든 형식의 복사해서 붙여 넣는 예시
- 🔄 양방향 변환 표
- 🎯 자주 쓰는 작업 흐름과 요령
- 🌟 참조 문서 스타일 안내
빠르게 찾아보고 곧바로 시작하기에 딱이에요!
데모
스크린샷
앞으로 더 추가될 예정이에요...
도구
convert-contents-
지원하는 형식 사이에서 내용을 변환해요
-
입력:
contents(string): 변환할 원본 내용(input_file이 없으면 필수)input_file(string): 입력 파일의 전체 경로(contents가 없으면 필수)input_format(string): 내용의 원본 형식(기본값은 markdown)output_format(string): 목표 형식(기본값은 markdown)output_file(string): 출력 파일의 전체 경로(pdf, docx, rst, latex, epub, odt, pptx 형식에는 필수)reference_doc(string): 스타일에 쓸 참조 문서의 경로(docx, odt, pptx 출력에서 지원하며, 파일은 출력 형식과 같아야 해요)defaults_file(string): 변환 옵션이 든 Pandoc defaults 파일(YAML)의 경로filters(array): 변환 중에 적용할 Pandoc 필터 경로 목록
-
방향별 지원 형식:
형식 읽기 쓰기 markdown ✅ ✅ html ✅ ✅ docx ✅ ✅ odt ✅ ✅ rst ✅ ✅ latex ✅ ✅ epub ✅ ✅ ipynb ✅ ✅ txt ✅ ✅ pdf ❌ ✅ pptx ❌ ✅ -
참고: 고급 형식(pdf, docx, rst, latex, epub, odt, pptx)은 output_file 경로가 필요해요
-
🔧 고급 기능
Defaults 파일 (YAML 설정)
Defaults 파일로 일관된 서식의 재사용 가능한 변환 템플릿을 만드세요.
# academic-paper.yaml
from: markdown
to: pdf
number-sections: true
toc: true
metadata:
title: "Academic Paper"
author: "Research Team"
사용 예: "Convert paper.md to PDF using defaults academic-paper.yaml and save as paper.pdf"
Pandoc 필터
처리를 더 풍부하게 하려면 사용자 지정 필터를 적용하세요.
사용 예: "Convert docs.md to HTML with filters ['/path/to/mermaid-filter.py'] and save as docs.html"
💡 더 많은 예시와 작업 흐름은 **CHEATSHEET.md**를 보세요
📊 지원하는 형식과 변환
양방향 변환 표
행은 원본 형식, 열은 목표 형식이에요. pandoc은 PDF와 PPTX를 읽지 못하므로 두 형식은 행에 없어요.
| 원본\목표 | MD | HTML | TXT | DOCX | ODT | RST | LaTeX | EPUB | IPYNB | PPTX | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Markdown | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| HTML | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| TXT | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| DOCX | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| ODT | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| RST | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| LaTeX | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| EPUB | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| IPYNB | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
쓰기 전용 형식에 대한 참고
PDF와 PPTX는 만들 수는 있지만 읽을 수는 없어요.
Pandoc은 PDF 리더를 낸 적이 없어요. Pandoc은 3.8.3(2025-12-01 출시)에서 PowerPoint 리더를 얻었지만, 이 프로젝트는 최소 pandoc 버전을 정하지 않고 Ubuntu 24.04가 여전히 pandoc 3.1.3을 제공하므로 pptx 입력은 제공하지 않아요. 진행 상황은 #54와 #49에서 추적해요.
PPTX 출력에는 특별한 pandoc 버전이 필요 없어요. PowerPoint 라이터는 pandoc 2.0.5부터 있었어요.
형식 분류
| 분류 | 형식 | 요구 사항 |
|---|---|---|
| 기본 | MD, HTML, TXT, IPYNB | 없음, 대화에 그대로 돌려줘요 |
| 고급 | DOCX, ODT, PDF, PPTX, RST, LaTeX, EPUB | output_file 경로를 꼭 줘야 해요 |
| 스타일 지정 | 참조 문서를 쓰는 DOCX, ODT, PPTX | 사용자 지정 템플릿 지원 ⭐ |
형식별 요구 사항
- PDF (.pdf) - TeX Live 설치가 필요해요
- DOCX (.docx), ODT (.odt), PPTX (.pptx) - 참조 문서로 사용자 지정 스타일을 지원하며, 참조 문서는 출력과 같은 형식이어야 해요
- 그 밖의 모든 형식 - 추가 요구 사항이 없어요
참고: 고급 형식의 경우
- 파일 이름과 확장자를 포함한 전체 파일 경로가 필요해요
- PDF 변환에는 TeX Live 설치가 필요해요(아래 「꼭 필요한 것」 절 참고 -> macOS:
brew install texlive) - 출력 경로를 주지 않으면:
- 기본 형식: 변환한 내용을 대화에 보여 줘요
- 고급 형식: 시스템 임시 폴더(Unix 계열은 /tmp/)에 저장될 수 있어요
사용법과 설정
참고: 아래 「꼭 필요한 것」에 적힌 필수 패키지를 먼저 모두 설치하세요.
게시된 패키지를 쓰려면
{
"mcpServers": {
"mcp-pandoc": {
"command": "uvx",
"args": ["mcp-pandoc"]
}
}
}
💡 빠른 시작: 복사해서 붙여 넣는 예시와 자주 쓰는 작업 흐름은 **CHEATSHEET.md**를 보세요.
⚠️ 중요한 참고
꼭 필요한 것
- Pandoc 설치
-
필수: 핵심 문서 변환 엔진인
pandoc을 설치하세요 -
설치:
# macOS brew install pandoc # Ubuntu/Debian sudo apt-get install pandoc # Windows # Download installer from: https://pandoc.org/installing.html -
확인:
pandoc --version
- UV 패키지 설치
-
필수:
uv패키지(uvx명령 포함)를 설치하세요 -
설치:
# macOS brew install uv # Windows/Linux pip install uv -
확인:
uvx --version
- PDF 변환 선행 조건: PDF로 변환해 저장해야 할 때만 필요해요
-
PDF 변환을 시도하기 전에 TeX Live가 설치돼 있어야 해요
-
설치 명령:
# Ubuntu/Debian sudo apt-get install texlive-xetex # macOS brew install texlive # Windows # Install MiKTeX or TeX Live from: # https://miktex.org/ or https://tug.org/texlive/
- 파일 경로 요구 사항
- 파일을 저장하거나 변환할 때는 파일 이름과 확장자를 포함한 전체 파일 경로를 꼭 줘야 해요
- 이 도구는 파일 이름이나 확장자를 자동으로 만들지 않아요
예시
✅ 올바른 사용:
# Converting content to PDF
"Convert this text to PDF and save as /path/to/document.pdf"
# Converting between file formats
"Convert /path/to/input.md to PDF and save as /path/to/output.pdf"
# Converting to DOCX with a reference document template
"Convert input.md to DOCX using template.docx as reference and save as output.docx"
# Converting to ODT with a reference document template
"Convert input.md to ODT using template.odt as reference and save as output.odt"
# Converting to a branded PowerPoint deck
"Convert slides.md to PPTX using template.pptx as reference and save as deck.pptx"
# Step-by-step reference document workflow
"First create a reference document: pandoc -o custom-reference.docx --print-default-data-file reference.docx" or if you already have one, use that
"Then convert with custom styling: Convert this text to DOCX using /path/to/custom-reference.docx as reference and save as /path/to/styled-output.docx"
❌ 잘못된 사용:
# Missing filename and extension
"Save this as PDF in /documents/"
# Missing complete path
"Convert this to PDF"
# Missing extension
"Save as /documents/story"
흔한 문제와 해결
-
PDF 변환이 실패할 때
- 오류: "xelatex not found"
- 해결: 먼저 TeX Live를 설치하세요(위의 설치 명령 참고)
-
파일 변환이 실패할 때
- 오류: "Invalid file path"
- 해결: 파일 이름과 확장자를 포함한 전체 경로를 주세요
- 예:
/path/to/말고/path/to/document.pdf
-
형식 변환이 실패할 때
- 오류: "Unsupported format"
- 해결: 지원하는 형식만 쓰세요:
- 기본: txt, html, markdown
- 고급: pdf, docx, rst, latex, epub
-
참조 문서 문제
- 오류: "Reference document not found"
- 해결: 참조 문서 경로가 있고 접근할 수 있는지 확인하세요
- 오류: "reference_doc must be a '.odt' file when output_format is 'odt'"
- 해결: 참조 문서는 출력과 같은 형식이어야 해요. Pandoc은 이를 스스로 검사하지 않아서, 형식이 안 맞는 참조 문서는 DOCX 출력에서는 조용히 무시되고 ODT 출력에서는 열 수 없는 파일이 만들어져요
- 참고: 참조 문서는 DOCX, ODT, PPTX 출력 형식에서 동작해요
- 만드는 법:
pandoc -o reference.docx --print-default-data-file reference.docx,reference.odt나reference.pptx도 같은 방식이에요
빠른 시작
claude_desktop_config.json 설정 파일로 직접 설치하기
- macOS:
open ~/Library/Application\ Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%/Claude/claude_desktop_config.json
a) 이 저장소를 개발하거나 기여할 때만
개발 · 미게시 서버 설정
ℹ️ <DIRECTORY>를 내 컴퓨터에 복제한 프로젝트 경로로 바꾸세요
"mcpServers": {
"mcp-pandoc": {
"command": "uv",
"args": [
"--directory",
"<DIRECTORY>/mcp-pandoc",
"run",
"mcp-pandoc"
]
}
}
b) 게시된 서버 설정 - 사용하는 사람은 이 설정을 쓰세요
"mcpServers": {
"mcp-pandoc": {
"command": "uvx",
"args": [
"mcp-pandoc"
]
}
}
- 문제가 생기면 이 CLI 말고 위의 「게시된 서버 설정」을 그대로 쓰세요.
참고: 로컬에 설정한 mcp-pandoc을 쓰려면 위의 「개발 · 미게시 서버 설정」 단계를 따르세요.
개발
테스트
지원하는 모든 양방향 변환을 검증하는 종합 테스트를 돌리려면 아래 명령을 쓰세요.
uv run pytest tests/test_conversions.py
이 명령은 하위 호환성을 지키고 도구의 핵심 기능을 확인해요.
빌드와 배포
배포용 패키지를 준비하려면:
- 의존성을 맞추고 잠금 파일을 갱신하세요:
uv sync
- 패키지 배포판을 빌드하세요:
uv build
그러면 dist/ 폴더에 소스 배포판과 wheel 배포판이 만들어져요.
- PyPI에 게시하세요:
uv publish
참고: PyPI 자격 증명은 환경 변수나 명령 옵션으로 정해야 해요.
- 토큰:
--token또는UV_PUBLISH_TOKEN - 또는 사용자 이름/비밀번호:
--username/UV_PUBLISH_USERNAME과--password/UV_PUBLISH_PASSWORD
디버깅
MCP 서버는 stdio로 돌아서 디버깅이 어려울 수 있어요. 가장 좋은 디버깅 경험을 위해 MCP Inspector를 강력히 권해요.
npm으로 아래 명령을 실행하면 MCP Inspector를 띄울 수 있어요.
npx @modelcontextprotocol/inspector uv --directory /Users/vivekvells/Desktop/code/ai/mcp-pandoc run mcp-pandoc
실행하면 Inspector가 브라우저에서 열 수 있는 URL을 보여 주고, 거기서 디버깅을 시작할 수 있어요.
기여하기
mcp-pandoc을 더 좋게 만드는 기여를 환영해요! 참여하는 방법은 이래요.
- 이슈 알리기: 버그를 찾았거나 기능을 제안하고 싶나요? GitHub Issues 페이지에 이슈를 열어 주세요.
- 풀 리퀘스트 보내기: 코드를 개선하거나 기능을 더하는 풀 리퀘스트를 만들어 주세요.

