Doc2md

🚀 doc2md

PDF、DOCX、PPTXファイルをディスク上のきれいなMarkdownファイルに変換するMCPサーバーです。他のMCPサーバーのリソースとしてすぐに使用できます。

🚀 クイックスタート

pip / uv

# pipでインストール
pip install doc2md

# またはuvで
uvx doc2md

Docker

docker run -v $(pwd):/data benguy1000/doc2md

✨ 主な機能

doc2mdは、PDF、DOCX、PPTXなどのバイナリ形式のドキュメントをMarkdown形式に変換することができます。これにより、LLMツールチェーン、RAGパイプライン、MCPサーバーでの利用が容易になります。

📦 インストール

上記のクイックスタートセクションに記載されている方法でインストールできます。

💻 使用例

基本的な使用法

convert_pdf_to_markdown

PDFファイルを構造化されたMarkdownに変換します。見出し、段落、リスト、表、改ページを保持します。 入力:

{
  "file_path": "/path/to/report.pdf",
  "output_dir": "/path/to/output",
  "overwrite": false
}

出力:

{
  "success": true,
  "output_path": "/path/to/output/report.md",
  "file_name": "report.md",
  "source_file": "report.pdf",
  "metadata": {
    "source_format": "pdf",
    "page_count": 12,
    "word_count": 4500,
    "has_images": true,
    "image_count": 3,
    "conversion_warnings": []
  }
}

convert_docx_to_markdown

DOCXファイルをMarkdownに変換します。見出し、書式（太字、斜体、取り消し線）、表、リスト、ハイパーリンク、脚注、コメントを保持します。 入力:

{
  "file_path": "/path/to/document.docx",
  "output_dir": "/path/to/output"
}

出力:

{
  "success": true,
  "output_path": "/path/to/output/document.md",
  "file_name": "document.md",
  "source_file": "document.docx",
  "metadata": {
    "source_format": "docx",
    "page_count": 1,
    "word_count": 2300,
    "has_images": false,
    "image_count": 0,
    "conversion_warnings": []
  }
}

convert_pptx_to_markdown

PPTXファイルをMarkdownに変換します。各スライドは、タイトル、本文、表、スピーカーノートを持つH2セクションになります。 入力:

{
  "file_path": "/path/to/deck.pptx",
  "output_dir": "/path/to/output"
}

出力:

{
  "success": true,
  "output_path": "/path/to/output/deck.md",
  "file_name": "deck.md",
  "source_file": "deck.pptx",
  "metadata": {
    "source_format": "pptx",
    "slide_count": 20,
    "word_count": 1800,
    "has_images": true,
    "image_count": 5,
    "conversion_warnings": []
  }
}

convert_auto

拡張子またはMIMEタイプからファイルタイプを自動検出し、適切なコンバーターにルーティングします。 入力:

{
  "file_path": "/path/to/any-document.pdf",
  "output_dir": "/path/to/output"
}

batch_convert

複数のファイルを一度に変換します。個々の失敗時にも続行します。 入力:

{
  "file_paths": [
    "/path/to/report.pdf",
    "/path/to/notes.docx",
    "/path/to/slides.pptx"
  ],
  "output_dir": "/path/to/output"
}

出力:

{
  "results": [
    { "success": true, "output_path": "/path/to/output/report.md", "..." : "..." },
    { "success": true, "output_path": "/path/to/output/notes.md", "..." : "..." },
    { "success": true, "output_path": "/path/to/output/slides.md", "..." : "..." }
  ],
  "total": 3,
  "successful": 3,
  "failed": 0
}

Base64入力 (すべての単一ファイルツール)

すべての単一ファイルツールは、ファイルパスの代わりにBase64エンコードされたコンテンツも受け入れます。

{
  "base64_content": "JVBERi0xLjQK...",
  "file_name": "report.pdf",
  "output_dir": "/path/to/output"
}

高度な使用法

セールスデッキのフォルダをMarkdownに変換して知識ベースに追加する

# ディレクトリ内のすべてのPPTXファイルでbatch_convertを使用
python -c "
from doc2md.tools.batch import batch_convert
from pathlib import Path

files = [str(f) for f in Path('/data/sales-decks').glob('*.pptx')]
result = batch_convert(files, output_dir='/data/knowledge-base')
print(f'Converted {result.successful}/{result.total} files')
"

変換されたドキュメントをベクトルデータベースにパイプする

1. doc2mdを使用してすべてのドキュメントを.mdファイルに変換します。
2. RAGパイプラインのドキュメントローダーを出力ディレクトリに向けます。
3. 一貫した見出し階層を持つきれいなMarkdownにより、チャンキングが信頼できるようになります。

Claude Desktopで使用してドキュメントを変換してからクエリする

1. Claude Desktopでdoc2mdをMCPサーバーとして構成します。
2. Claudeに「/path/to/quarterly-report.pdfをMarkdownに変換して」と尋ねます。
3. .mdファイルがディスクに書き込まれ、後続のクエリで参照できます。

📚 ドキュメント

MCPクライアント設定

Claude Desktop (ローカルPython)

claude_desktop_config.jsonに追加します。

{
  "mcpServers": {
    "doc2md": {
      "command": "python",
      "args": ["-m", "doc2md"],
      "env": {
        "TRANSPORT": "stdio"
      }
    }
  }
}

Claude Desktop (Docker)

DockerベースのMCPサーバーでClaude Desktopを実行する場合、コンテナがアクセスできるようにファイルディレクトリをマウントします。

{
  "mcpServers": {
    "doc2md": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/path/to/your/files:/data",
        "benguy1000/doc2md"
      ]
    }
  }
}

⚠️ 重要提示

サンドボックスまたはDocker環境では、ホストのファイルパス（例：/mnt/user-data/uploads/）がコンテナ内からアクセスできない場合があります。ファイルパスが解決されない場合は、代わりにbase64_contentとfile_nameパラメータを使用してください。LLMは、パスが見つからない診断を受け取ったときに自動的にこのアプローチに切り替えます。

Claude Code

プロジェクトの.mcp.jsonまたはグローバルMCP設定に追加します。

{
  "mcpServers": {
    "doc2md": {
      "command": "python",
      "args": ["-m", "doc2md"]
    }
  }
}

⚠️ 重要提示

Claude Codeは、プロジェクトディレクトリをCWDとしてMCPサーバーを起動します。base64_contentを使用してoutput_dirを指定しない場合、変換された.mdファイルはプロジェクトディレクトリに書き込まれます。出力先を制御するには、output_dirを使用してください。

Cursor

{
  "mcpServers": {
    "doc2md": {
      "command": "python",
      "args": ["-m", "doc2md"],
      "transport": "stdio"
    }
  }
}

汎用MCPクライアント (Docker + SSE)

{
  "mcpServers": {
    "doc2md": {
      "url": "http://localhost:3000/sse",
      "transport": "sse"
    }
  }
}

設定

Dockerの使用方法

doc2mdがソースファイルを読み取り、出力を書き込めるように、ファイルディレクトリをマウントします。

# stdioモード (MCPクライアント用)
docker run -v $(pwd):/data benguy1000/doc2md

# SSEモード (ネットワークアクセス用)
docker run -p 3000:3000 -v $(pwd):/data -e TRANSPORT=sse benguy1000/doc2md

出力の.mdファイルは、ホストファイルシステムのマウントされたディレクトリに表示されます。

🔧 技術詳細

doc2mdは、PDF、DOCX、PPTXなどのバイナリ形式のドキュメントをMarkdown形式に変換するためのMCPサーバーです。これにより、LLMツールチェーン、RAGパイプライン、MCPサーバーでの利用が容易になります。

🤝 コントリビュート

1. リポジトリをクローンします。
2. 開発用の依存関係をインストールします: pip install -e ".[dev]"
3. テストを実行します: pytest
4. リントを実行します: ruff check src/ tests/
5. フォーマットを実行します: ruff format src/ tests/

📄 ライセンス

MIT — Copyright (c) 2025 benguy1000