MD-DOCX Converter
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 以获取完整的元素映射以及关于哪些内容被保留、近似处理或丢弃的说明。
Related MCP server: MarkltDown MCP Server
系统要求
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-converter2. 安装依赖
pip install markdown-it-py python-docx3. 创建桌面快捷方式
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 格式将近似处理为 粗体:
Word 格式 | Markdown 输出 |
下划线 |
|
高亮 |
|
小型大写字母 |
|
字体颜色 | 去除(保留文本) |
图像
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-docxClaude Code — 注册 MCP 服务器:
claude mcp add md-docx-converter --transport stdio -- uvx mcp-md-docxClaude Desktop — 添加到 %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"md-docx-converter": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-md-docx"]
}
}
}公开的工具
工具 | 功能 |
| 读取 |
| 根据 AI 编写的 Markdown 文本创建 |
| 将磁盘上的 |
| 将磁盘上的 |
配置完成后,您可以说:
“Read
report.docxand summarise it”“Turn this into a Word document and save it to my Desktop”
“Convert all the bullet points in
notes.docxinto 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 许可证:
库 | 用途 | 许可证 |
模型上下文协议服务器框架 | MIT | |
GitHub Flavored Markdown 解析器 | MIT | |
读取和写入 Word | MIT |
完整的许可证文本已在 THIRD_PARTY_NOTICES.md 中转载。
Available Tools
4 toolsconvert_docx_file_to_mdA
Convert a Word (.docx) file to a Markdown (.md) file. The output is saved alongside the input file. Returns the Markdown content.
Inputs: path (required). Returns: result
convert_md_file_to_docxA
Convert a Markdown (.md) file to a Word (.docx) file. The output is saved alongside the input file with the same name and .docx extension.
Inputs: path (required). Returns: result
read_docxA
Read a Word (.docx) document and return its full content as Markdown text. Use this when the user asks you to read, summarise, edit, or work with a Word document.
Inputs: path (required). Returns: result
write_docxA
Convert Markdown text to a Word (.docx) document and save it to disk. Use this when the user asks you to create or save a Word document from text or Markdown content. The output_path should be an absolute path ending in .docx.
Inputs: markdown (required), output_path (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
The tools have significant overlap in purpose, particularly between convert_docx_file_to_md and read_docx (both convert DOCX to Markdown), and between convert_md_file_to_docx and write_docx (both convert Markdown to DOCX). The descriptions attempt to differentiate use cases (file conversion vs. content reading/writing), but an agent could easily misselect between these pairs due to unclear functional boundaries.
The tool names follow a consistent verb_noun pattern with snake_case throughout (e.g., convert_docx_file_to_md, read_docx). The only minor deviation is that some names include 'file' while others do not, but overall the naming is predictable and readable.
With 4 tools, the count is reasonable for a conversion-focused server, but it feels borderline thin given the overlapping functionality. A more streamlined set might have 2-3 tools instead, as the current count includes redundancy that doesn't add clear value to the surface.
For a DOCX-Markdown conversion domain, the tools cover the core bidirectional conversion operations and basic file handling. However, there are minor gaps, such as no tool for editing or manipulating the content in between conversions, which agents might need to work around by combining tools or external processing.
Maintenance
Related MCP Connectors
Convert PDF, Word, Excel, PowerPoint, e-mails and web pages to clean Markdown for LLMs.
Convert PDF, DOCX, XLSX and 25 other formats to clean Markdown for LLMs and RAG. No key or account.
Document to Markdown: convert Word, Excel, PowerPoint and PDF files to Markdown for an LLM.
Turn Markdown and AI answers into Word (.docx) with native equations, or into PDF.
Related MCP Servers
- AlicenseAqualityDmaintenanceConverts Markdown documents to professional Word documents with advanced formatting capabilities including mathematical formulas, custom styling, tables, images, headers/footers, and watermarks.483 npm14MIT
- FlicenseNot gradedqualityDmaintenanceConverts files (PDF, Word, images, etc.) to Markdown within Claude Desktop to reduce token usage.-
- AlicenseAqualityCmaintenanceConverts documents between Markdown, PDF, DOCX, and HTML locally with AI-friendly Markdown output and secure file access.6MIT
- AlicenseAqualityBmaintenanceEnables Claude to create, edit, mail-merge, convert and preview documents by driving a locally installed WordCraft engine headless, covering DOCX, PDF, ODT, RTF, HTML, Markdown and LaTeX. Supports templates, tables, images, comments, tracked changes, merge fields from CSV/XLSX/ODS, page rendering and folder-wide batch processing.11Apache 2.0