MD2Doc

将 Markdown 文件转换为符合公文格式规范的 Word (.docx) 文件。

功能

• 基于 pandoc + python-docx 的 Markdown → Word 转换

• 内置中国公文格式规范（黑体标题、仿宋正文、固定行距 28 磅等）

• 支持通过格式要求文件自定义样式

• 支持 HTML 表格转换（含 colspan/rowspan 合并单元格）

• 自动处理东亚字体、图片行距、表格自动适配

• MCP Server：可在 Claude Code 中直接调用转换和分析工具

• 语义分析：检查文档结构和内容，生成修改建议报告

• Markdown → Excel：将文档中的 HTML/管道表格转换为带样式的 .xlsx（微软雅黑、细边框、合并单元格、自动列宽行高）

Related MCP server: Word MCP Server

安装

环境要求

• Python >= 3.12

• pandoc（需在 ~/.local/bin/pandoc 或 PATH 中）

安装依赖

git clone <repo-url>
cd md2doc
uv sync

CLI 命令行使用

基本用法

# 使用默认公文格式转换
uv run python scripts/md2docx.py <input.md>

# 指定输出路径
uv run python scripts/md2docx.py <input.md> -o output.docx

# 跳过格式设置（纯 pandoc 输出）
uv run python scripts/md2docx.py <input.md> --no-format

自定义格式

# 使用自定义格式要求文件
uv run python scripts/md2docx.py <input.md> -f 格式要求.md

# 叠加参考模板（模板样式覆盖格式要求）
uv run python scripts/md2docx.py <input.md> -f 格式要求.md -r template.docx

格式要求文件格式

参照项目根目录下的 格式要求.md：

## H1（一级标题）
- 字体：黑体，三号，加粗
- 对齐方式：左对齐
- 行距：固定值28磅
- 间距：段前0行，段后0行
- 大纲级别：1级
- 特殊格式：无

## H2（二级标题）
- 字体：仿宋_GB2312，小三，加粗
- 对齐方式：左对齐
- 行距：固定值28磅
- ...

## 正文
- 字体：仿宋_GB2312，四号
- 对齐方式：两端对齐
- 行距：固定值28磅
- 特殊格式：首行缩进2字符

## 表格
- 字体：仿宋_GB2312，五号
- 对齐方式：居中对齐
- 行距：单倍行距

支持的字号：三号(16pt)、小三(15pt)、四号(14pt)、小四(12pt)、五号(10.5pt)、小五(9pt)

MCP Server

md2doc 提供 MCP（Model Context Protocol）服务器，可在 Claude Code 中直接使用。

配置 MCP 服务器

在 ~/.claude.json 的 mcpServers 中添加：

{
  "mcpServers": {
    "md2doc": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/md2doc",
        "md2doc-mcp"
      ]
    }
  }
}

将 /path/to/md2doc 替换为实际的项目路径。配置后重启 Claude Code 即可生效。使用 /mcp 命令查看是否加载成功。

可用工具

1. convert_markdown_to_docx — 转换 Markdown 为 Word

将 Markdown 文件转换为符合公文格式规范的 .docx 文件。

格式设置的优先级：未指定 format_spec 时，自动使用项目根目录下的 格式要求.md（可通过修改 mcp_server.py 中的 DEFAULT_FORMAT_SPEC_PATH 配置）；如果该文件也不存在，则使用内置的默认公文格式。

使用示例对话：

用户：帮我把 report.md 转成 Word 文档

Claude：好的。你有特定格式要求吗？可以提供格式要求的 markdown 文件，或者参考的 docx 模板。

用户：没有特殊要求，用默认格式就行

Claude：调用 convert_markdown_to_docx，使用默认格式转换

用户：用 custom-format.md 的格式转换

Claude：调用 convert_markdown_to_docx，format_spec="custom-format.md"

2. convert_markdown_to_xlsx — 转换 Markdown 为 Excel

将 Markdown 文档中的表格转换为带样式的 .xlsx 文件。按文档顺序提取所有 HTML <table> 与 Markdown 管道表格，每个表格生成一个 worksheet。

保留的格式：

• HTML 表格：colspan/rowspan 合并单元格、<b> 粗体、<th> 表头、<br> 换行、style 中的 text-align 对齐

• 管道表格：首行为表头；分隔行 :--- / ---: / :---: 决定列对齐

• 样式：微软雅黑、细边框、表头加粗 + 浅灰底纹、垂直居中、自动换行、按内容估算列宽与行高

• Sheet 名取表格前最近的 # 标题，否则为 表格N

使用示例对话：

用户：把这个课程大纲 md 转成 Excel

Claude：调用 convert_markdown_to_xlsx，自动生成 .xlsx

用户：帮我把 report.md 里所有表格导出成 xlsx

Claude：调用 convert_markdown_to_xlsx，输出每个表格一个 sheet

3. analyze_and_suggest — 文档语义分析

分析 Markdown 文档的结构和内容，在同目录下生成 xx-修改建议.md 修改建议报告。

分析类别（共 6 类）：

输出文件格式：

# 修改建议 — report.md

> 生成时间: 2026-06-28 14:30:00
> 分析文件: /path/to/report.md
> 总行数: 1523
> 发现问题: 12 项（错误 2 项，警告 7 项，提示 3 项）

---

## 一、标题层级问题（2项）

| 行号 | 严重度 | 问题描述 |
|------|--------|----------|
| 42   | 警告   | 标题层级跳跃: H1 → H3，缺少 H2 |
| --   | 错误   | 缺少一级标题 (H1) |

## 二、必要章节检查（1项）

| 行号 | 严重度 | 问题描述 |
|------|--------|----------|
| --   | 警告   | 未检测到「日期信息」，建议检查是否遗漏 |
...

使用示例对话：

用户：帮我检查一下这篇文档有什么问题

Claude：调用 analyze_and_suggest，分析后返回修改建议文件路径和问题摘要

MCP 服务器配置项

默认格式要求文件的路径在 src/md2doc/mcp_server.py 中配置：

# 修改此行即可更改默认格式
DEFAULT_FORMAT_SPEC_PATH: str | None = str(
    Path(__file__).parent.parent.parent / "格式要求.md"
)

• 设为其他路径：使用该路径的格式要求文件

• 设为 None：跳过加载默认格式文件，直接使用内置的硬编码默认格式

项目结构

md2doc/
├── scripts/
│   ├── md2docx.py          # Markdown → Word CLI 转换脚本（独立运行）
│   └── md2xlsx.py          # Markdown → Excel CLI 转换脚本（独立运行）
├── src/md2doc/
│   ├── __init__.py          # 包元数据
│   ├── converter.py         # Markdown → Word 核心包装器（异常驱动的 API）
│   ├── xlsx_converter.py    # Markdown → Excel 核心包装器（异常驱动的 API）
│   ├── analyzer.py          # 语义分析引擎
│   └── mcp_server.py        # MCP 服务器入口
├── 格式要求.md               # 默认公文格式规范
├── 测试用例/                 # 测试文档
│   ├── AI场景落地全流程实战.md
│   └── 模版.xlsx
└── pyproject.toml

默认公文格式规范

许可证

MIT