Document Converter

A local-first MCP server for converting documents between Markdown, PDF, DOCX, and HTML, with environment diagnostics and workspace-level configuration.

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

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

Features

• 7 conversion tools: Markdown <-> PDF, Markdown <-> DOCX, Markdown <-> HTML, PDF -> Markdown
• doctor tool: Diagnose local environment (Node.js, Pandoc, Python, MarkItDown, PDF engines)
• Configuration file: .document-converter.json for workspace-level defaults
• 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 concurrency control, dry run, include/exclude filters
• PDF style options: Margin, section numbering, syntax highlighting, metadata
• HTML style options: Themes, embedded CSS, self-contained output, syntax highlighting
• DOCX image extraction: Extract embedded images with metadata reporting
• PDF sidecar recovery: Accurate Markdown restoration from PDFs generated with preserveSource: true
• 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.

• Windows: cjkMainFont: "Microsoft YaHei"
• macOS: cjkMainFont: "Songti SC"
• Linux: cjkMainFont: "Noto Sans CJK SC"

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 DOCX extraction:
python -m pip install -U "markitdown[docx]"

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

markitdown installed does not guarantee PDF or DOCX support is available.

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

Configuration File

Place .document-converter.json in your workspace root to set defaults for all tools.

Example:

{
  "defaults": {
    "pdfEngine": "xelatex",
    "cjkMainFont": "Microsoft YaHei",
    "pageSize": "A4",
    "theme": "github",
    "cleanForLLM": true,
    "overwrite": false
  },
  "batch": {
    "maxConcurrency": 2,
    "continueOnError": true
  },
  "security": {
    "maxFileSizeMB": 50
  }
}

Precedence:

tool args > .document-converter.json > built-in defaults

Notes:

• The config file is read from the workspace root only (not nested directories).
• Config values cannot bypass pathGuard -- paths must still be within the workspace.
• overwrite defaults to false in the config for safety; do not set it to true unless intentional.
• For Chinese/CJK PDF generation, recommended config:
  • Windows: "pdfEngine": "xelatex", "cjkMainFont": "Microsoft YaHei"
  • macOS: "pdfEngine": "xelatex", "cjkMainFont": "Songti SC"
  • Linux: "pdfEngine": "xelatex", "cjkMainFont": "Noto Sans CJK SC"

Tools

1. doctor

Check the local environment for document-converter-mcp dependencies.

This tool never fails due to missing dependencies -- missing tools appear as false in the output with warnings.

Checks:

• Node.js version
• Workspace path, existence, writability
• Pandoc availability and version
• Python availability
• MarkItDown availability and PDF support
• PDF engines: pdflatex, xelatex, lualatex, wkhtmltopdf, weasyprint, typst
• Recommendations for missing dependencies

Example output:

{
  "success": true,
  "summary": "Environment check completed.",
  "data": {
    "node": { "available": true, "version": "v22.18.0" },
    "workspace": { "path": "E:/MCPWorkDir", "exists": true, "writable": true },
    "pandoc": { "available": true, "version": "pandoc 3.8.2" },
    "python": { "available": true, "command": "python" },
    "markitdown": { "available": true, "pdfSupport": true },
    "pdfEngines": {
      "pdflatex": true,
      "xelatex": true,
      "lualatex": true,
      "wkhtmltopdf": false,
      "weasyprint": false,
      "typst": false
    },
    "recommendations": []
  },
  "warnings": [],
  "error": null
}

2. markdown_to_pdf

Convert Markdown to PDF using Pandoc.

Note: Pandoc requires an external PDF engine (LaTeX distribution or alternative) to generate PDFs.

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

Parameter	Type	Required	Default	Description
inputPath	string	Yes	--	Input Markdown file path (relative to workspace)
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
cjkMainFont	string	No	--	CJK main font for Chinese/Japanese/Korean documents (e.g. "Microsoft YaHei", "SimSun", "Noto Sans CJK SC")
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
margin	string	No	--	Page margin in safe format (e.g. '1in', '2cm', '20mm', '72pt')
numberSections	boolean	No	false	Number section headings in the PDF
highlightStyle	string	No	--	Code highlight theme: default, tango, pygments, kate, monochrome, github, darkblue, emacs, friendly, fruity, native, trac, borland
metadata	object	No	--	Additional metadata key-value pairs

Sidecar files (when preserveSource=true):

• document.pdf.source.md -- Original Markdown content
• document.pdf.meta.json -- Conversion metadata

3. 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
strictMarkdown	boolean	No	false	Reject input if Markdown has structural issues
overwrite	boolean	No	false	Allow overwriting existing files

4. 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 from the DOCX
imageDir	string	No	Auto-derived	Directory for extracted images (must be within workspace). If omitted, defaults to ${outputBasename}_media
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

Image extraction:

When extractImages=true, the response includes:

{
  "imageCount": 2,
  "imageDir": "out/document_media",
  "images": [
    {
      "filename": "media/image1.png",
      "sizeBytes": 12345
    }
  ]
}

Even if no images are found:

{
  "imageCount": 0,
  "imageDir": "out/document_media",
  "images": []
}

Supported image extensions: .png, .jpg, .jpeg, .gif, .webp, .svg, .bmp, .tif, .tiff.

Path safety: imageDir is validated against path traversal. Values like ../outside-media will be rejected with an error containing "Access denied" and "workspace".

5. 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 是内容提取，不是版式或语义结构还原。

普通 PDF 通常不保存 Markdown 语义。标题、表格、代码块、列表、阅读顺序都可能无法可靠恢复。

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

Sidecar recovery:

If the PDF was generated by this server with preserveSource: true, the original Markdown is available as sidecar files (document.pdf.source.md, document.pdf.meta.json). The default preferSourceSidecar: true will automatically find and return it.

Quality report:

Sidecar recovery mode:

{
  "quality": {
    "mode": "source-sidecar",
    "layoutPreserved": true,
    "headingsReliable": true,
    "tablesReliable": true,
    "codeBlocksReliable": true,
    "readingOrderReliable": true
  }
}

Plain text extraction mode:

{
  "quality": {
    "mode": "text-extraction",
    "layoutPreserved": false,
    "headingsReliable": false,
    "tablesReliable": false,
    "codeBlocksReliable": false,
    "readingOrderReliable": false
  }
}

6. 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 (validated via workspace pathGuard)
standalone	boolean	No	true	Generate complete HTML document with head/body
strictMarkdown	boolean	No	false	Reject input if Markdown has structural issues
overwrite	boolean	No	false	Allow overwriting existing files
theme	string	No	--	Pandoc HTML theme: default, github, academic, monochrome, bookish, mangoe, slaper, quarto
embedCss	boolean	No	false	Embed CSS and resources into the HTML document
selfContained	boolean	No	false	Generate a self-contained single-file HTML
highlightStyle	string	No	--	Code highlight theme: default, tango, pygments, kate, monochrome, github, darkblue, emacs, friendly, fruity, native, trac, borland

theme=github is ideal for README-style documentation. embedCss=true embeds CSS directly into the HTML. selfContained=true produces a single HTML file with all resources inline.

7. batch_convert

Convert all matching files in a directory from one format to another.

Parameter	Type	Required	Default	Description
inputDir	string	Yes	--	Source directory (relative to workspace)
outputDir	string	Yes	--	Destination directory (relative to workspace)
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 output for LLM consumption
dryRun	boolean	No	false	Generate a conversion plan without writing files
include	string[]	No	--	Only convert files matching these glob patterns (e.g. ["report-*.md"])
exclude	string[]	No	--	Skip files matching these glob patterns (e.g. ["draft-*"])
maxConcurrency	number	No	1	Max concurrent conversions (1-8). Useful for low-memory machines.
continueOnError	boolean	No	true	Continue processing other files when one fails

Dry run example:

{
  "inputDir": "docs/source",
  "outputDir": "docs/published",
  "from": "md",
  "to": "pdf",
  "dryRun": true
}

Returns a plan with plannedCount but does not write any files.

Return structure:

{
  "success": true,
  "summary": "Batch conversion completed: 4 succeeded, 0 failed, 0 skipped.",
  "total": 4,
  "plannedCount": 4,
  "skippedCount": 0,
  "successCount": 4,
  "failedCount": 0,
  "durationMs": 1201,
  "results": [...]
}

Usage Examples

Run doctor

Tool: doctor
Args: {}

Create .document-converter.json

{
  "defaults": {
    "pdfEngine": "xelatex",
    "cjkMainFont": "Microsoft YaHei",
    "overwrite": false
  }
}

Markdown to Chinese PDF using config

With .document-converter.json setting pdfEngine: "xelatex" and cjkMainFont: "Microsoft YaHei":

Tool: markdown_to_pdf
Args: {
  "inputPath": "docs/chinese-report.md",
  "title": "季度报告",
  "toc": true,
  "pageSize": "A4",
  "preserveSource": true,
  "overwrite": true
}

Markdown to PDF with preserveSource

Tool: markdown_to_pdf
Args: {
  "inputPath": "docs/report.md",
  "outputPath": "docs/report.pdf",
  "preserveSource": true,
  "overwrite": true
}

Generates docs/report.pdf.source.md and docs/report.pdf.meta.json for accurate recovery.

PDF to Markdown using source sidecar

Tool: pdf_to_markdown
Args: {
  "inputPath": "docs/report.pdf",
  "preferSourceSidecar": true
}

Automatically finds and returns the original Markdown from the sidecar file.

Markdown to HTML with GitHub theme

Tool: markdown_to_html
Args: {
  "inputPath": "docs/readme.md",
  "theme": "github",
  "standalone": true,
  "selfContained": true
}

Batch convert with dry run

Tool: batch_convert
Args: {
  "inputDir": "docs/articles",
  "outputDir": "docs/html",
  "from": "md",
  "to": "html",
  "dryRun": true
}

Batch convert with include/exclude

Tool: batch_convert
Args: {
  "inputDir": "docs/articles",
  "outputDir": "docs/published",
  "from": "md",
  "to": "pdf",
  "recursive": true,
  "include": ["report-*.md"],
  "exclude": ["draft-*", "internal-*"],
  "maxConcurrency": 2,
  "continueOnError": true,
  "overwrite": true
}

DOCX to Markdown with image extraction

Tool: docx_to_markdown
Args: {
  "inputPath": "docs/presentation.docx",
  "extractImages": true,
  "imageDir": "docs/presentation_media",
  "overwrite": true
}

Returns imageCount, imageDir, and images array in the response.

Security

This server implements strict security measures:

• Workspace isolation: All file access is confined to a configured workspace directory (DOC_CONVERTER_WORKSPACE env var)
• 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 (configurable via config file)
• No shell injection: All commands use spawn() with argument arrays
• No overwrite by default: Existing files are protected unless explicitly allowed
• Config file cannot bypass pathGuard: Configuration defaults respect the same path safety rules as tool arguments

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 with image metadata
• PDF -> Markdown -- For text extraction only. Use preferSourceSidecar: true for PDFs generated by this server.

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
  • Use preserveSource: true instead when generating the PDF

推荐工作流

推荐

• Markdown -> PDF -- 高质量的 PDF 输出
• Markdown -> DOCX -- 高质量的 Word 输出
• Markdown -> HTML -- 高质量的 HTML 输出
• DOCX -> Markdown -- 良好的文本提取和图片元数据
• PDF -> Markdown -- 仅用于内容提取。对本服务生成的 PDF 请使用 preferSourceSidecar: true 精确恢复。

不推荐

• Markdown -> PDF -> Markdown 用于结构恢复
  • PDF 不保存 Markdown 语义（标题、表格、代码块、列表、阅读顺序）
  • 往返转换将丢失结构信息
  • 生成 PDF 时请使用 preserveSource: true

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