使用说明

MCP-MD-PDF:Markdown到Word/PDF转换器

一个简单可靠的模型上下文协议（MCP）服务器，可将Markdown文件转换为专业Word（.docx）和PDF文档，并完全支持 .dotx 模板。

背景

这个工具是出于实际需要而诞生的。我们经常用Markdown编写文档、指南和技术说明——它快速、轻便、易于版本。但是，当需要将这些文件交付给客户或专业展示时，我们通常希望它们与我们的项目或公司风格相匹配：干净的布局、一致的字体、品牌封面和精美的格式。

因此，我们构建了一个简单的流程，而不是每次都手动执行：

转换Markdown→ Word（.docx使用 .dotx 模板）→ PDF

通过使用Word模板，我们可以一次性应用自己的设计，并保持每个文档的一致性。这就是这个小项目的由来——一种快速的方法，可以将Markdown变成漂亮的、随时可以共享的文档，看起来像是属于你的组织。

特性

🚀 快速转换 –从Markdown到Word或PDF只需几秒钟
🎨 模板支撑 –申请 .dotx 一致的品牌风格模板
📦 批处理 –一次转换多个文件
🔧 灵活的输出 –选择 .docx, .pdf，或两者皆有
🤖 AI就绪 –旨在与Claude和其他MCP兼容的AI工具顺利集成

安装

选择最适合您需求的安装方法：

方法	代码下载？	PDF支持	最适合
uvx （选项1）	❌ 否	✅ 是（需要LibreOffice）	克劳德桌面用户
点（选项2）	❌ 否	✅ 是（需要LibreOffice）	Python包用户
来源（选项3）	✅ 是	✅ 是（需要LibreOffice）	开发人员

选项1：使用 `uvx` （推荐-无需下载代码）

最适合： 想要最简单安装的Claude Desktop用户。

要求：

Python 3.10+
PDF转换：
- 窗户： Microsoft Word（使用COM自动化）
- macOS： LibreOffice(brew install --cask libreoffice)
- Linux： LibreOffice(sudo apt-get install libreoffice)

安装：

# No code download needed - uvx handles everything
uvx mcp-md-pdf

Claude桌面设置：

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "md-pdf": {
      "command": "uvx",
      "args": ["mcp-md-pdf"]
    }
  }
}

重新启动克劳德桌面 以使更改生效。

📖 看配置节用于配置文件位置和替代设置。

选项2：使用 `pip` （无需下载代码）

最适合： 希望安装为Python包的用户。

要求：

Python 3.10+
对于PDF转换（与选项1相同）：
- 窗户： 微软 Word
- macOS/Linux： LibreOffice

安装：

# Install from PyPI (when published)
pip install mcp-md-pdf

# Or install with development dependencies
pip install "mcp-md-pdf[dev]"

Claude桌面设置：

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "md-pdf": {
      "command": "python",
      "args": ["-m", "md_pdf_mcp.server"]
    }
  }
}

重新启动克劳德桌面 以使更改生效。

📖 看配置节用于配置文件位置和替代设置。

选项3：来源（需要下载代码）

最适合： 想要修改代码或做出贡献的开发人员。

要求：

Git
Python 3.10+
用于PDF转换（与上述相同）

安装：

# Step 1: Clone the repository
git clone https://github.com/sham-devs/mcp-md-pdf.git
cd mcp-md-pdf

# Step 2: Install in development mode
pip install -e .

# Step 3: (Optional) Install dev dependencies
pip install -e ".[dev]"

Claude桌面设置：

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "md-pdf": {
      "command": "python",
      "args": ["-m", "md_pdf_mcp.server"]
    }
  }
}

重新启动克劳德桌面 以使更改生效。

📖 看配置节用于配置文件位置和替代设置。

配置

步骤1：查找配置文件

窗户：

%APPDATA%\Claude\claude_desktop_config.json

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

步骤2：添加MCP服务器

打开配置文件并添加mcp md pdf服务器：

选项A：使用uvx（推荐）

{
  "mcpServers": {
    "md-pdf": {
      "command": "uvx",
      "args": ["mcp-md-pdf"]
    }
  }
}

选项B：本地安装

{
  "mcpServers": {
    "md-pdf": {
      "command": "python",
      "args": ["-m", "md_pdf_mcp.server"]
    }
  }
}

选项C：使用环境变量

{
  "mcpServers": {
    "md-pdf": {
      "command": "python",
      "args": ["-m", "md_pdf_mcp.server"],
      "env": {
        "PYTHONPATH": "/path/to/mcp-md-pdf"
      }
    }
  }
}

步骤3：重新启动克劳德桌面

关闭并重新打开Claude Desktop以使更改生效。

用法

使用克劳德桌面

安装后，重新启动Claude Desktop，只需询问：

Convert my README.md to Word format

Convert docs.md to PDF using my company-template.dotx

Convert all markdown files in the docs folder to both Word and PDF

MCP工具

1. `convert_markdown`

将单个Markdown文件转换为Word或PDF。

参数：

markdown_path （str） –通往 .md 文件
output_path （str） –输出基本路径（无扩展）
output_format （str） – "docx", "pdf"，或 "both" （默认值： "docx")
template_path （str，可选） –通往 .dotx 模板

示例：

# Create Word document
convert_markdown("README.md", "output", "docx")

# Create PDF with template
convert_markdown("doc.md", "result", "pdf", "template.dotx")

# Create both formats
convert_markdown("guide.md", "final", "both", "company.dotx")

2. `convert_markdown_batch`

一次转换多个Markdown文件。

参数：

markdown_files （列表[str]） –列表 .md 文件
output_dir （str） –输出目录
output_format （str） – "docx", "pdf"，或 "both"
template_path （str，可选） –共享 .dotx 模板

例子：

convert_markdown_batch(
  ["doc1.md", "doc2.md", "doc3.md"],
  "output",
  "both",
  "template.dotx"
)

3. `list_supported_formats`

列出支持的格式及其功能。

支持的Markdown功能

功能	支持	备注
标题（H1–H6）	✅	`#` 通过 `######`，模板回退
加粗 / 斜体	✅	Markdown标准语法
内联代码	✅	单色，灰色背景
代码块	✅	带背景和边框的专业造型
项目符号和编号列表	✅	最多嵌套3个级别
表格	✅	具有页眉样式和内联格式
区块链报价	✅	带有左边框和背景阴影的斜体文本
横向规则	✅	`---`
Unicode表情符号（&J）	✅	完全支持UTF-8

有关详细的功能覆盖率分析，请参阅 docs/MARKDOWN-COVERAGE.md

模板支撑

使用一个 .dotx 用于定义文档样式的Word模板：

自定义标题、字体和颜色
页边距和布局
页脚
品牌和徽标放置
目录格式

如果没有提供模板，则使用干净的默认设计。

PDF转换设置

重要提示： PDF转换需要LibreOffice（或Windows上的Microsoft Word）来保留所有DOCX格式。

为什么选择LibreOffice？

LibreOffice是 必需的 用于PDF转换，因为它保留了DOCX文件的所有格式：

✅ 颜色、背景、边框 -专业造型完好无损
✅ 代码块 -语法高亮显示和背景保留
✅ 表格 -标题、边框和单元格样式得以保留
✅ 模板样式 - .dotx 模板格式转换为PDF
✅ 字体和间距 -排版保持像素完美

替代方法（Pandoc等）会丢失格式 -他们将DOCX视为纯文本标记，在PDF转换过程中剥离视觉样式。

DOCX转换（所有平台）

✅ 开箱即用-无需额外软件！

PDF转换（特定于平台）

windows用户

选项A:Microsoft Word（最适合Windows）

如果您安装了Microsoft Word：

# Install Python COM automation library
pip install pywin32

就是这样！转换器将自动使用Word进行PDF转换。

选项B:LibreOffice（如果没有Word，建议使用）

# Method 1: Direct download (easiest)
# Visit: https://www.libreoffice.org/download/

# Method 2: Using Chocolatey package manager
choco install libreoffice

# Method 3: Using winget (Windows Package Manager)
winget install TheDocumentFoundation.LibreOffice

验证安装：

# Check if LibreOffice is installed
where.exe soffice
# Should output: C:\Program Files\LibreOffice\program\soffice.exe

macOS用户

在macOS上转换PDF需要LibreOffice （不支持本机MS Word COM）。

安装（选择一种方法）：

# Method 1: Homebrew (RECOMMENDED - easiest updates)
brew install --cask libreoffice

# Method 2: Direct download
# Visit: https://www.libreoffice.org/download/
# Download LibreOffice_25.x.x_MacOS_aarch64.dmg (M1/M2/M3)
# Or LibreOffice_25.x.x_MacOS_x86-64.dmg (Intel Macs)

系统要求：

macOS 10.15（Catalina）或更新版本
约800 MB磁盘空间
适用于英特尔和苹果硅（M1/M2/M3）

验证安装：

which soffice
# Should output: /Applications/LibreOffice.app/Contents/MacOS/soffice

libreoffice --version
# Should output: LibreOffice 25.x.x or higher

Linux用户

Ubuntu/Debian（推荐方法）：

# Update package list
sudo apt-get update

# Install LibreOffice (headless mode supported)
sudo apt-get install -y libreoffice libreoffice-writer

# Optional: Install additional fonts for better compatibility
sudo apt-get install -y fonts-liberation fonts-dejavu

对于无头服务器（CI/CD）：

# Minimal installation without GUI components
sudo apt-get install -y libreoffice-writer libreoffice-calc \
  libxinerama1 libfontconfig1 libdbus-glib-1-2 libcairo2 \
  libcups2 libglu1-mesa libsm6

Fedora/RHEL：

sudo dnf install libreoffice libreoffice-writer

Arch Linux：

sudo pacman -S libreoffice-fresh

验证安装：

libreoffice --version
# Should output: LibreOffice 7.x or 25.x

# Test headless mode
soffice --headless --version
# Should output version without GUI

平台说明

DOCX转换： 适用于所有平台（Windows、macOS、Linux）- 无需额外软件
PDF转换： 具有自动平台检测功能的跨平台：
- 窗户： 使用Microsoft Word（如果已安装）或LibreOffice
- macOS/Linux： 在无头模式下使用LibreOffice

为什么选择LibreOffice for PDF？ LibreOffice保留全部转换为PDF时的DOCX格式：

✅ 颜色、背景和边框
✅ 专业代码块样式（#F5F5F5背景）
✅ 区块报价边框（蓝色左边框）
✅ 带彩色背景的表头
✅ .dotx文件中的模板样式
✅ 字体、间距和布局

需求

Python 3.10+
Pillow （图像处理）
python-docx （单词生成）
pywin32 （仅限Windows）
fastmcp （MCP框架）

发展

# Clone the repository
git clone https://github.com/sham-devs/mcp-md-pdf.git
cd mcp-md-pdf

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/md_pdf_mcp --cov-report=html

# Format code
black src/ tests/
ruff check src/ tests/

测试

盖子：

标记语言→ 词性转换
模板应用
MCP服务器工具
Unicode、表情符号和大小写

结构：

tests/
├── conftest.py
├── test_converter.py
├── test_server.py
└── README.md

示例

# Run the MCP server directly
python -m md_pdf_mcp.server

或通过以下方式检查：

npx @modelcontextprotocol/inspector python -m md_pdf_mcp.server

示例用法：

User: Convert my README.md to Word format
→ Created: README.docx

User: Create a PDF with our company template
→ Created: guide.pdf

User: Convert all docs to both formats
→ Batch Conversion Complete (5 succeeded, 0 failed)

故障排除

服务器未显示在Claude桌面中

验证 claude_desktop_config.json 是有效的JSON（没有尾随逗号）
检查Python路径是否适合您的系统
查看克劳德桌面日志：
- 窗户： %APPDATA%\Claude\logs\
- macOS： ~/Library/Logs/Claude/
完全重新启动克劳德桌面

Python路径问题

验证您的Python安装：

python --version
# or
python3 --version

如果命令不起作用，请找到您的Python路径：

窗户： where python
macOS/Linux： which python3

使用正确的路径更新配置文件。

PDF转换失败

错误： pywin32 library required for PDF conversion on Windows

修复（Windows）：

pip install pywin32

错误： LibreOffice not found

修复（macOS）：

brew install --cask libreoffice

修复（Ubuntu/Debian）：

sudo apt-get install libreoffice libreoffice-writer

修复（Fedora）：

sudo dnf install libreoffice

模板未加载

错误： 无效或缺失 .dotx 文件

修复：

验证文件路径和扩展名是否正确
确保模板文件存在并且可访问
尝试无模板转换以隔离问题

导入错误

错误： ModuleNotFoundError: No module named 'fastmcp'

修复：

跑 pip install -e . 从项目目录
或者从PyPI安装： pip install mcp-md-pdf

MCP检验员测试

对于高级调试，直接测试服务器：

npx @modelcontextprotocol/inspector python -m md_pdf_mcp.server

这将打开一个web界面，直接与MCP工具进行交互。

许可证

MIT许可证——见 LICENSE 文件。

贡献

欢迎拉取请求。如果您有改进转换、模板或新格式的想法，我们很乐意看到。

鸣谢

内置于❤️ 使用FastMCP框架-- 创建Markdown是为了使Markdown文档看起来像真实的报告，而不仅仅是GitHub上的文本。

使用说明

MCP-MD-PDF:Markdown到Word/PDF转换器

背景

特性

安装

选项1：使用 uvx （推荐-无需下载代码）

选项2：使用 pip （无需下载代码）

选项3：来源（需要下载代码）

配置

步骤1：查找配置文件

步骤2：添加MCP服务器

步骤3：重新启动克劳德桌面

用法

使用克劳德桌面

MCP工具

1. convert_markdown

2. convert_markdown_batch

3. list_supported_formats

支持的Markdown功能

模板支撑

PDF转换设置

为什么选择LibreOffice？

DOCX转换（所有平台）

PDF转换（特定于平台）

windows用户

macOS用户

Linux用户

平台说明

需求

发展

测试

示例

故障排除

服务器未显示在Claude桌面中

Python路径问题

PDF转换失败

模板未加载

导入错误

MCP检验员测试

许可证

贡献

鸣谢

相关 MCP

多格式文档转Markdown转换器

文档格式转换服务

PDF处理工具集

文档处理服务器

HTTP请求服务器

文档转Markdown MCP服务器

选项1：使用 `uvx` （推荐-无需下载代码）

选项2：使用 `pip` （无需下载代码）

1. `convert_markdown`

2. `convert_markdown_batch`

3. `list_supported_formats`