MD-DOCX 转换器

一个用于 Markdown (.md) 和 Microsoft Word (.docx) 之间双向转换的 Python 工具。旨在方便在 Word 文档与 Claude、ChatGPT 和 GitHub Copilot 等 AI 工具之间迁移内容。

功能特点

• 将 .md 转换为 .docx，并保持正确的标题层级（标题、标题 1–9）

• 将 .docx 转换为干净的 GitHub Flavored Markdown (GFM)

• 通过简单的桌面快捷方式运行 — 无需命令行知识

• 支持标题、粗体/斜体/删除线、列表、任务列表、表格、引用块、代码块、图像和超链接

请参阅 MarkdownSyntax.md 以获取完整的元素映射以及关于哪些内容被保留、近似处理或丢弃的说明。

系统要求

• Windows 10/11

• Python 3.11+

• 以下 Python 包（通过 pip 安装）：

pip install markdown-it-py python-docx

设置

1. 克隆仓库

git clone https://github.com/cjwpenner/md-docx-converter.git
cd md-docx-converter

2. 安装依赖

pip install markdown-it-py python-docx

3. 创建桌面快捷方式

pip install pywin32
python create_shortcut.py

这将在您的 Windows 桌面上创建一个 MD-DOCX Converter 快捷方式。pywin32 仅用于创建快捷方式 — 运行转换器本身不需要它。

4. 运行转换器

双击桌面上的 MD-DOCX Converter。控制台窗口将打开并提示：

MD ↔ DOCX Converter
--------------------
Enter file path:

粘贴或输入您的 .md 或 .docx 文件的完整路径并按回车键。转换后的文件将保存在同一目录下，并替换扩展名。

您也可以直接从命令行运行：

python md_docx_converter/converter.py

转换说明

标题层级

标题级别的映射取决于上下文：

• MD → DOCX：如果文档中只有一个 #，它将成为 Word 的 标题 (Title)。所有其他标题下移一级。如果有多个 # 标题，它们都将成为 标题 1 (Heading 1)，且没有标题样式。

• DOCX → MD：如果文档具有 标题 (Title) 样式，它将变为 #。所有标题相应上移。如果没有标题样式，标题 1 (Heading 1) 将变为 #。

有损元素

没有 Markdown 等效项的 Word 格式将近似处理为 粗体：

图像

• DOCX → MD：嵌入的图像会被提取到输出 .md 文件旁边的 {filename}_images/ 文件夹中。

• MD → DOCX：通过相对路径引用的图像会被重新嵌入。缺失的图像将显示为 [image not found: path]。

Claude Code 集成

此工具可以作为 插件（推荐 — 两条命令即可完成所有操作）或独立的 MCP 服务器（用于手动设置或 Claude Desktop）与 Claude Code 集成。

选项 A：Claude Code 插件（推荐）

该插件捆绑了 MCP 服务器配置和一个 /convert 技能。在 Claude Code 中运行以下两条命令：

/plugin marketplace add cjwpenner/md-docx-converter
/plugin install md-docx-converter@md-docx-converter

就是这样 — 无需进一步配置。运行 /reload-plugins 后，Claude 将获得转换工具，您可以直接调用该技能：

/md-docx-converter:convert path/to/file.md
/md-docx-converter:convert path/to/report.docx

或者直接自然地提问：“Convert this to a Word document”，Claude 将自动使用这些工具。

选项 B：仅 MCP 服务器（手动设置）

如果您只想使用 MCP 工具而不需要插件，或者您正在配置 Claude Desktop 而不是 Claude Code，请使用此选项。

安装包：

pip install mcp-md-docx

Claude Code — 注册 MCP 服务器：

claude mcp add md-docx-converter --transport stdio -- uvx mcp-md-docx

Claude Desktop — 添加到 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "md-docx-converter": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-md-docx"]
    }
  }
}

公开的工具

配置完成后，您可以说：

• “Read report.docx and summarise it”

• “Turn this into a Word document and save it to my Desktop”

• “Convert all the bullet points in notes.docx into a table”

项目结构

md_docx_converter/
├── converter.py       # CLI entry point
├── md_to_docx.py      # Markdown → Word conversion
├── docx_to_md.py      # Word → Markdown conversion
├── heading_mapper.py  # Heading hierarchy pre-scan logic
├── image_handler.py   # Image extraction and embedding
└── launch.pyw         # Desktop shortcut launcher
mcp_md_docx/
├── server.py          # MCP server (four tools)
└── __main__.py        # Entry point for python -m mcp_md_docx
create_shortcut.py     # One-time shortcut setup script
pyproject.toml         # PyPI packaging config

许可证

本项目采用 GNU 通用公共许可证 v3.0 (GPLv3) 授权。您可以自由使用、修改和分发本软件，前提是任何衍生作品也必须在相同的许可证下分发。

请参阅 LICENSE 获取完整的许可证文本。

第三方库

本项目依赖于以下开源库，均采用 MIT 许可证：

完整的许可证文本已在 THIRD_PARTY_NOTICES.md 中转载。