@lifeng688/document-converter-mcp

A local-first MCP server for converting documents between Markdown, PDF, DOCX, and HTML, with AI-friendly Markdown output and safe file access.

English: This project focuses on AI-friendly document conversion, not pixel-perfect layout reconstruction.

中文: 本项目重点是 AI 友好的文档转换，而不是像素级版式还原。

Features

• 6 conversion tools: Markdown ↔ PDF, Markdown ↔ DOCX, Markdown ↔ HTML, PDF → Markdown
• Dual engine support: Pandoc (primary) + MarkItDown (enhanced PDF/DOCX extraction)
• Safe file access: Workspace-isolated path validation, sensitive file blocking, no-overwrite-by-default
• Secure command execution: Spawn-based, no shell injection, structured errors with timeouts
• AI-friendly output: Optional cleanForLLM flag for cleaner Markdown
• Batch processing: Convert entire directories with per-file error tolerance
• Structured results: Consistent JSON response format across all tools

Supported Formats

Source	Targets
Markdown (.md)	PDF, DOCX, HTML
DOCX (.docx)	Markdown
PDF (.pdf)	Markdown

Installation

Prerequisites

1. Node.js >= 18.0.0
2. Pandoc >= 3.0
3. Python 3 >= 3.8 (optional, for MarkItDown)

PDF Engine (required for Markdown → PDF)

Pandoc can convert Markdown to PDF, but it requires an external PDF engine.

Engine	Install	Notes
pdflatex (default)	MiKTeX (Windows), TeX Live (Linux/macOS)	Most common, ~2 GB install
xelatex	TeX Live / MiKTeX	Recommended for Chinese/CJK documents
lualatex	TeX Live / MiKTeX	Lua-based LaTeX engine
wkhtmltopdf	apt install wkhtmltopdf / brew install wkhtmltopdf	Lightweight HTML-to-PDF engine
weasyprint	pip install weasyprint	Python-based HTML-to-PDF
typst	cargo install typst	Modern, fast typesetting system

Chinese documents: Use pdfEngine: "xelatex" with a TeX Live / MiKTeX installation that includes the ctex package.

Install Pandoc

macOS:

brew install pandoc

Ubuntu/Debian:

sudo apt-get update && sudo apt-get install -y pandoc

Windows: Download from https://pandoc.org/installing.html

Verify:

pandoc --version

Install MarkItDown (optional, recommended for PDF → Markdown)

pip install markitdown

Verify:

python3 -c "import markitdown; print('ok')"

PDF support requires optional dependencies:

# For PDF extraction only:
python -m pip install -U "markitdown[pdf]"

# For all optional converters (PDF, EPUB, HTML, etc.):
python -m pip install -U "markitdown[all]"

markitdown exists does not guarantee PDF support is installed.

Install the Server

npm install -g @lifeng688/document-converter-mcp

Or use directly via npx:

npx @lifeng688/document-converter-mcp

For development, clone the repo and build locally:

git clone https://github.com/guanweiqiang/document-convert-mcp.git
cd document-convert-mcp
npm install
npm run build

MCP Client Configuration

Install the package globally first:

npm install -g @lifeng688/document-converter-mcp

Claude Desktop

Edit your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "document-converter": {
      "command": "npx",
      "args": ["-y", "@lifeng688/document-converter-mcp"],
      "env": {
        "DOC_CONVERTER_WORKSPACE": "E:/MCPWorkDir"
      }
    }
  }
}

Or if installed globally, use the local path:

{
  "mcpServers": {
    "document-converter": {
      "command": "document-converter-mcp",
      "env": {
        "DOC_CONVERTER_WORKSPACE": "E:/MCPWorkDir"
      }
    }
  }
}

Sample configs are in examples/:

• mcp.json — MCP Inspector config
• claude-desktop-config.json — Claude Desktop config

Tools

1. markdown_to_pdf

Convert Markdown to PDF using Pandoc.

Note: Pandoc requires an external PDF engine (LaTeX distribution or alternative) to generate PDFs. See Installation for setup instructions.

中文文档：pdflatex 不支持中文 Unicode 字符。中文 Markdown 转 PDF 请使用 pdfEngine: "xelatex"（推荐）或 lualatex。

Parameter	Type	Required	Default	Description
inputPath	string	Yes	—	Input Markdown file path
outputPath	string	No	Auto-derived	Output PDF path
title	string	No	—	PDF document title
toc	boolean	No	false	Include table of contents
pageSize	enum	No	A4	Page size: A4 or Letter
theme	enum	No	default	Theme: default, github, academic
pdfEngine	enum	No	Pandoc default	PDF engine: pdflatex, xelatex, lualatex, wkhtmltopdf, weasyprint, typst. Leave unset to let Pandoc choose.
cjkMainFont	string	No	—	CJK main font name for Chinese/Japanese/Korean documents (e.g. "Microsoft YaHei", "SimSun", "Noto Sans CJK SC"). Passed as -V CJKmainfont:<font>.
preserveSource	boolean	No	false	Save original Markdown as sidecar files (sample.pdf.source.md, sample.pdf.meta.json) for accurate PDF-to-Markdown recovery.
strictMarkdown	boolean	No	false	Reject input if Markdown has structural issues like unclosed code blocks.
overwrite	boolean	No	false	Allow overwriting existing files

2. markdown_to_docx

Convert Markdown to DOCX using Pandoc.

Parameter	Type	Required	Default	Description
inputPath	string	Yes	—	Input Markdown file path
outputPath	string	No	Auto-derived	Output DOCX path
referenceDocx	string	No	—	Word template file
toc	boolean	No	false	Include table of contents. Note: when converting back to Markdown, the TOC may appear as plain content.
strictMarkdown	boolean	No	false	Reject input if Markdown has structural issues like unclosed code blocks.
overwrite	boolean	No	false	Allow overwriting existing files

3. docx_to_markdown

Convert DOCX to Markdown using Pandoc or MarkItDown.

Parameter	Type	Required	Default	Description
inputPath	string	Yes	—	Input DOCX file path
outputPath	string	No	Auto-derived	Output Markdown path
extractImages	boolean	No	false	Extract embedded images
imageDir	string	No	—	Directory for extracted images
engine	enum	No	pandoc	Engine: pandoc or markitdown
markdownFlavor	enum	No	gfm	Markdown dialect: gfm (GitHub Flavored), commonmark, or pandoc
cleanForLLM	boolean	No	false	Clean Markdown for AI consumption
overwrite	boolean	No	false	Allow overwriting existing files

4. pdf_to_markdown

Extract text from PDF to Markdown.

Warning: This is content extraction, not layout reconstruction. Scanned PDFs, complex tables, two-column papers, and mathematical formulas may not convert reliably. For scanned PDFs, OCR is required (not included).

PDF → Markdown is content extraction, not layout or semantic structure reconstruction.

PDF 转 Markdown 是内容提取，不是版式或语义结构还原。

普通 PDF 通常不保存 Markdown 语义。

标题、表格、代码块、列表、阅读顺序都可能无法可靠恢复。

MarkItDown PDF support: By default pip install markitdown installs only core text/DOCX support. PDF extraction requires the optional [pdf] extra.

Sidecar recovery: If the PDF was generated by this server with preserveSource: true, the original Markdown is available as a sidecar file. The default preferSourceSidecar: true will automatically find and return it.

Parameter	Type	Required	Default	Description
inputPath	string	Yes	—	Input PDF file path
outputPath	string	No	Auto-derived	Output Markdown path
engine	enum	No	markitdown	Engine: markitdown or pandoc
cleanForLLM	boolean	No	false	Clean Markdown for AI consumption
preferSourceSidecar	boolean	No	true	First check for a .source.md sidecar file. If found, return original Markdown instead of extracting PDF text.
overwrite	boolean	No	false	Allow overwriting existing files

5. markdown_to_html

Convert Markdown to HTML using Pandoc.

Parameter	Type	Required	Default	Description
inputPath	string	Yes	—	Input Markdown file path
outputPath	string	No	Auto-derived	Output HTML path
cssPath	string	No	—	External CSS file path
standalone	boolean	No	true	Generate complete HTML document
strictMarkdown	boolean	No	false	Reject input if Markdown has structural issues like unclosed code blocks.
overwrite	boolean	No	false	Allow overwriting existing files

6. batch_convert

Convert all matching files in a directory.

Parameter	Type	Required	Default	Description
inputDir	string	Yes	—	Source directory
outputDir	string	Yes	—	Destination directory
from	enum	Yes	—	Source format: md, markdown, docx, pdf
to	enum	Yes	—	Target format: md, markdown, docx, pdf, html
recursive	boolean	No	false	Traverse subdirectories
overwrite	boolean	No	false	Overwrite existing files
cleanForLLM	boolean	No	false	Clean Markdown for AI consumption

Usage Examples

Convert a single Markdown file to PDF

Tool: markdown_to_pdf
Args: {
  "inputPath": "reports/quarterly.md",
  "toc": true,
  "pageSize": "Letter"
}

Convert Markdown to PDF with xelatex (for Chinese documents)

pdflatex 不适合中文文档，会报 LaTeX Error: Unicode character not set up for use with LaTeX。 中文 Markdown 转 PDF 推荐使用 xelatex，并指定 CJK 字体。

• Windows: cjkMainFont: "Microsoft YaHei" 或 "SimSun" 或 "SimHei"
• macOS: cjkMainFont: "Songti SC" 或 "Heiti SC"
• Linux: cjkMainFont: "Noto Sans CJK SC" (需安装 fonts-noto-cjk 包)

For Chinese Markdown documents, use pdfEngine='xelatex' and set cjkMainFont. On Windows, recommended fonts are Microsoft YaHei, SimSun, or SimHei.

Tool: markdown_to_pdf
Args: {
  "inputPath": "sample.md",
  "outputPath": "sample.pdf",
  "toc": true,
  "pageSize": "A4",
  "pdfEngine": "xelatex",
  "cjkMainFont": "Microsoft YaHei",
  "preserveSource": true,
  "overwrite": true
}

Extract text from a PDF for AI analysis

Tool: pdf_to_markdown
Args: {
  "inputPath": "papers/research.pdf",
  "engine": "markitdown",
  "cleanForLLM": true
}

Batch convert all Markdown files to PDF

Tool: batch_convert
Args: {
  "inputDir": "docs/source",
  "outputDir": "docs/published",
  "from": "md",
  "to": "pdf",
  "recursive": true,
  "overwrite": true
}

Security

This server implements strict security measures:

• Workspace isolation: All file access is confined to a configured workspace directory
• Path traversal prevention: .. sequences and absolute path escapes are blocked
• Sensitive file blocking: .env, .ssh/, .npmrc, etc. are never accessible
• File size limits: Input files over 50 MB are rejected by default
• No shell injection: All commands use spawn() with argument arrays
• No overwrite by default: Existing files are protected unless explicitly allowed

See docs/security.md for full details.

Recommended Workflows

Good

• Markdown → PDF — High-quality PDF output with Pandoc
• Markdown → DOCX — High-quality Word output
• Markdown → HTML — High-quality HTML output
• DOCX → Markdown — Good text extraction
• PDF → Markdown — For text extraction only. See Conversion Quality for limitations.

Not recommended

• Markdown → PDF → Markdown for structure recovery
  • PDFs do not preserve Markdown semantics (headings, tables, code blocks, lists, reading order)
  • The round-trip will lose structural information

Accurate recovery from PDF

If you need to recover the original Markdown from a PDF generated by this server, use preserveSource: true when calling markdown_to_pdf:

{
  "inputPath": "sample.md",
  "outputPath": "sample.pdf",
  "preserveSource": true,
  "overwrite": true
}

This generates sidecar files (sample.pdf.source.md, sample.pdf.meta.json). Then when calling pdf_to_markdown, the default preferSourceSidecar: true will automatically find and return the original Markdown.

推荐工作流

推荐

• Markdown → PDF — 高质量的 PDF 输出
• Markdown → DOCX — 高质量的 Word 输出
• Markdown → HTML — 高质量的 HTML 输出
• DOCX → Markdown — 良好的文本提取
• PDF → Markdown — 仅用于内容提取。有关限制请参见 Conversion Quality 部分。

不推荐

• Markdown → PDF → Markdown 用于结构恢复
  • PDF 不保存 Markdown 语义（标题、表格、代码块、列表、阅读顺序）
  • 往返转换将丢失结构信息

从 PDF 精确恢复

如果需要从本工具生成的 PDF 恢复原始 Markdown，请在生成 PDF 时启用 preserveSource: true：

{
  "inputPath": "sample.md",
  "outputPath": "sample.pdf",
  "preserveSource": true,
  "overwrite": true
}

这将生成 sidecar 文件（sample.pdf.source.md, sample.pdf.meta.json）。然后在调用 pdf_to_markdown 时，默认的 preferSourceSidecar: true 会自动查找并返回原始 Markdown。

Conversion Quality

This project focuses on AI-friendly document conversion, not pixel-perfect layout reconstruction.

See docs/conversion-quality.md for format-specific quality notes and engine comparisons.

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode (hot reload)
npm run dev

# Type check without emitting
npm run typecheck

License

MIT