mcp-pandoc: A Document Conversion MCP Server

Model Context Protocol servers オープンソースプロジェクトに正式に収録されています。🎉

概要

pandoc を使用してドキュメント形式を変換するための Model Context Protocol サーバーです。このサーバーは、書式と構造を維持しながら、さまざまなドキュメント形式間でコンテンツを変換するためのツールを提供します。

mcp-pandoc は現在、開発の初期段階にあることにご注意ください。PDF サポートは開発中であり、サーバーの改善を続ける中で、機能と利用可能なツールは変更・拡張される可能性があります。

クレジット: このプロジェクトは、ドキュメント変換に Pandoc Python package を使用しており、これがこのプロジェクトの基盤となっています。

📋 クイックリファレンス

mcp-pandoc を初めてお使いですか? 次の内容については 📖 CHEATSHEET.md をご確認ください

• ⚡ すべての形式に対応したコピー＆ペースト可能な例
• 🔄 双方向変換マトリクス
• 🎯 一般的なワークフローとプロのヒント
• 🌟 参照ドキュメントのスタイリングガイド

素早く調べたいときや、すぐに始めたいときに最適です!

デモ

🎥 YouTube で視聴する

スクリーンショット

さらに追加予定です...

ツール

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"

使用例：「defaults academic-paper.yaml を使用して paper.md を PDF に変換し、paper.pdf として保存する」

Pandoc フィルター

カスタムフィルターを適用して処理を強化できます。

使用例：「filters ['/path/to/mermaid-filter.py'] を使用して docs.md を HTML に変換し、docs.html として保存する」

💡 包括的な例とワークフローについては、 CHEATSHEET.md を参照してください。

📊 対応フォーマットと変換

双方向変換マトリックス

行はソースフォーマット、列はターゲットフォーマットです。pandoc では PDF と PPTX を読み込めないため、これらの行はありません。

書き込み専用フォーマットについて

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 から搭載されています。

形式カテゴリ

形式ごとの要件

• 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

2. UV パッケージのインストール

• 必須：uv パッケージをインストールします（uvx コマンドが含まれます）

• インストール方法：

  # macOS
  brew install uv
  
  # Windows/Linux
  pip install uv
  

• 確認：uvx --version

3. 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/
  

4. ファイルパスの要件

• ファイルを保存または変換する際は、ファイル名と拡張子を含む完全なファイルパスを指定する必要があります
• ツールがファイル名や拡張子を自動生成することはありません

例

✅ 正しい使用方法：

# 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」
   • 解決方法：参照ドキュメントのパスが存在し、アクセス可能であることを確認します
   • エラー：「output_format が 'odt' の場合、reference_doc は '.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) このリポジトリのローカル開発およびコントリビューション専用

"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

2. パッケージの配布物をビルドします：

uv build

これにより、ソース配布物と wheel 配布物が dist/ ディレクトリに作成されます。

3. 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 が表示されます。その URL にブラウザーからアクセスして、デバッグを開始できます。

コントリビューション

mcp-pandoc の改善に向けたコントリビューションを歓迎します。参加方法は次のとおりです：

1. 問題を報告する：バグを見つけた場合や機能をリクエストしたい場合は、GitHub Issues ページで issue を作成してください。
2. プルリクエストを送信する：プルリクエストを作成して、コードベースを改善したり、機能を追加したりできます。