Doc2md

🚀 doc2md

doc2md 是一個 MCP 服務器，它可以將 PDF、DOCX 和 PPTX 文件轉換為乾淨的 Markdown 文件並保存到磁盤，這些文件可直接作為其他 MCP 服務器的資源使用。

🚀 快速開始

使用 pip 或 uv 安裝

# 使用 pip 安裝
pip install doc2md

# 或者使用 uv 安裝
uvx doc2md

使用 Docker 安裝

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

✨ 主要特性

LLM 工具鏈、RAG 管道和 MCP 服務器在處理純文本和 Markdown 時表現最佳。但許多組織有大量以二進制格式（如 PDF、Word 文檔和 PowerPoint 演示文稿）存儲的文檔。doc2md 可以將這些文件統一轉換為文件系統上的 .md 文件，從而可以立即將它們作為 MCP 資源引用、導入向量數據庫或添加到知識庫中，無需任何手動清理。

📦 安裝指南

pip / uv

# 使用 pip 安裝
pip install doc2md

# 或者使用 uv 安裝
uvx doc2md

Docker

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

💻 使用示例

基礎用法

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 以項目目錄作為當前工作目錄啟動 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"
    }
  }
}

高級用法

工具使用示例

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 並用於知識庫

# 使用 batch_convert 處理目錄中的所有 PPTX 文件
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 文件將寫入磁盤，並可在後續查詢中引用。

📚 詳細文檔

配置

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 文件將出現在主機文件系統的掛載目錄中。

🔧 技術細節

本項目的開發和使用涉及到 Python 環境，使用 pip 或 uv 進行安裝，也支持 Docker 部署。在 MCP 客戶端配置方面，針對不同的客戶端（如 Claude Desktop、Claude Code、Cursor 等）提供了相應的配置示例。工具方面，提供了多種文件轉換工具，包括 convert_pdf_to_markdown、convert_docx_to_markdown 等，並且支持批量轉換和 Base64 輸入。

📄 許可證

MIT — 版權所有 (c) 2025 benguy1000