본문으로 건너뛰기
MCP 서버 전체 목록

mcp-pandoc

  • 추천0
  • GitHub 별588
  • 문서라이선스MIT

pandoc으로 문서 형식을 바꾸는 MCP 서버. Markdown · HTML · DOCX · PDF · PPTX · EPUB 등을 서식을 지킨 채 변환해요(uvx). MIT

원본:vivekVells/mcp-pandoc

설치 방법은 설치 탭에 정리했어요.

설명

Downloads CI

image

MseeP.ai 보안 평가 배지

Glama 배지

mcp-pandoc: 문서 변환 MCP 서버

Model Context Protocol 서버 오픈소스 프로젝트에 공식으로 포함됐어요. 🎉

개요

pandoc으로 문서 형식을 바꾸는 Model Context Protocol 서버예요. 서식과 구조를 지킨 채 내용을 여러 문서 형식 사이에서 변환하는 도구를 제공해요.

mcp-pandoc은 아직 초기 개발 단계예요. PDF 지원은 개발 중이고, 서버를 계속 개선하면서 기능과 도구는 바뀌거나 늘어날 수 있어요.

감사의 말: 이 프로젝트는 문서 변환에 Pandoc Python 패키지를 쓰며, 그것이 프로젝트의 기반이에요.

📋 빠른 참조

mcp-pandoc이 처음이라면 **📖 CHEATSHEET.md**를 보세요.

  • ⚡ 모든 형식의 복사해서 붙여 넣는 예시
  • 🔄 양방향 변환 표
  • 🎯 자주 쓰는 작업 흐름과 요령
  • 🌟 참조 문서 스타일 안내

빠르게 찾아보고 곧바로 시작하기에 딱이에요!

데모

mcp-pandoc - v1: MCP 서버로 Claude에서 매끄럽게 문서 형식 변환하기

🎥 YouTube에서 보기

스크린샷

스크린샷 1

스크린샷 2

스크린샷 3

스크린샷 4

스크린샷 5

앞으로 더 추가될 예정이에요...

도구

  1. 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를 읽지 못하므로 두 형식은 행에 없어요.

원본\목표MDHTMLTXTDOCXODTRSTLaTeXEPUBIPYNBPDFPPTX
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, EPUBoutput_file 경로를 꼭 줘야 해요
스타일 지정참조 문서를 쓰는 DOCX, ODT, PPTX사용자 지정 템플릿 지원 ⭐

형식별 요구 사항

  • PDF (.pdf) - TeX Live 설치가 필요해요
  • DOCX (.docx), ODT (.odt), PPTX (.pptx) - 참조 문서로 사용자 지정 스타일을 지원하며, 참조 문서는 출력과 같은 형식이어야 해요
  • 그 밖의 모든 형식 - 추가 요구 사항이 없어요

참고: 고급 형식의 경우

  1. 파일 이름과 확장자를 포함한 전체 파일 경로가 필요해요
  2. PDF 변환에는 TeX Live 설치가 필요해요(아래 「꼭 필요한 것」 절 참고 -> macOS: brew install texlive)
  3. 출력 경로를 주지 않으면:
    • 기본 형식: 변환한 내용을 대화에 보여 줘요
    • 고급 형식: 시스템 임시 폴더(Unix 계열은 /tmp/)에 저장될 수 있어요

사용법과 설정

참고: 아래 「꼭 필요한 것」에 적힌 필수 패키지를 먼저 모두 설치하세요.

게시된 패키지를 쓰려면

{
  "mcpServers": {
    "mcp-pandoc": {
      "command": "uvx",
      "args": ["mcp-pandoc"]
    }
  }
}

💡 빠른 시작: 복사해서 붙여 넣는 예시와 자주 쓰는 작업 흐름은 **CHEATSHEET.md**를 보세요.

⚠️ 중요한 참고

꼭 필요한 것

  1. Pandoc 설치
  • 필수: 핵심 문서 변환 엔진인 pandoc을 설치하세요

  • 설치:

    # macOS
    brew install pandoc
    
    # Ubuntu/Debian
    sudo apt-get install pandoc
    
    # Windows
    # Download installer from: https://pandoc.org/installing.html
  • 확인: pandoc --version

  1. UV 패키지 설치
  • 필수: uv 패키지(uvx 명령 포함)를 설치하세요

  • 설치:

    # macOS
    brew install uv
    
    # Windows/Linux
    pip install uv
  • 확인: uvx --version

  1. 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/
  1. 파일 경로 요구 사항
  • 파일을 저장하거나 변환할 때는 파일 이름과 확장자를 포함한 전체 파일 경로를 꼭 줘야 해요
  • 이 도구는 파일 이름이나 확장자를 자동으로 만들지 않아요

예시

✅ 올바른 사용:

# 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"

흔한 문제와 해결

  1. PDF 변환이 실패할 때

    • 오류: "xelatex not found"
    • 해결: 먼저 TeX Live를 설치하세요(위의 설치 명령 참고)
  2. 파일 변환이 실패할 때

    • 오류: "Invalid file path"
    • 해결: 파일 이름과 확장자를 포함한 전체 경로를 주세요
    • 예: /path/to/ 말고 /path/to/document.pdf
  3. 형식 변환이 실패할 때

    • 오류: "Unsupported format"
    • 해결: 지원하는 형식만 쓰세요:
      • 기본: txt, html, markdown
      • 고급: pdf, docx, rst, latex, epub
  4. 참조 문서 문제

    • 오류: "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

이 명령은 하위 호환성을 지키고 도구의 핵심 기능을 확인해요.

빌드와 배포

배포용 패키지를 준비하려면:

  1. 의존성을 맞추고 잠금 파일을 갱신하세요:
uv sync
  1. 패키지 배포판을 빌드하세요:
uv build

그러면 dist/ 폴더에 소스 배포판과 wheel 배포판이 만들어져요.

  1. 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을 더 좋게 만드는 기여를 환영해요! 참여하는 방법은 이래요.

  1. 이슈 알리기: 버그를 찾았거나 기능을 제안하고 싶나요? GitHub Issues 페이지에 이슈를 열어 주세요.
  2. 풀 리퀘스트 보내기: 코드를 개선하거나 기능을 더하는 풀 리퀘스트를 만들어 주세요.

저장소: https://github.com/vivekVells/mcp-pandoc