Skip to main content
Glama

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 文件。

参数

类型

必填

说明

input_path

string

✓

输入的 Markdown 文件绝对路径

output_path

string

输出 .docx 路径,默认为 <输入目录>/<文件名>.docx

format_spec

string

格式要求 Markdown 文件路径(如 格式要求.md)

reference_docx

string

参考 .docx 模板,样式会叠加在格式要求之上

extract_media

string

提取媒体文件的目标目录

skip_format

bool

设为 true 跳过所有格式设置(纯 pandoc 输出)

no_cache_template

bool

设为 true 强制重新生成缓存的参考模板

格式设置的优先级:未指定 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。

参数

类型

必填

说明

input_path

string

✓

输入的 Markdown 文件绝对路径

output_path

string

输出 .xlsx 路径,默认为 <输入目录>/<文件名>.xlsx

font_name

string

字体名(默认微软雅黑)

body_size

int

正文字号(默认 11)

保留的格式:

  • 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 修改建议报告。

参数

类型

必填

说明

input_path

string

✓

输入的 Markdown 文件绝对路径

分析类别(共 6 类):

类别

检查内容

标题层级问题

层级跳跃(H1→H3)、缺少主标题、多个 H1、标题过长

必要章节检查

公文常见要素:标题模式、发文机关、日期、附件/附录

格式问题

失效的图片引用、HTML 表格标签不匹配

内容问题

空章节、占位符文本、重复段落、段落过长

编号连续性

编号间隙、重新编号、格式不一致

中文标点规范

半角标点、英文引号、缺少句末标点

输出文件格式:

# 修改建议 — 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

默认公文格式规范

样式

字体

字号

加粗

对齐

行距

缩进

H1(一级标题)

黑体

三号 16pt

✓

左对齐

固定 28pt

无

H2(二级标题)

仿宋_GB2312

小三 15pt

✓

左对齐

固定 28pt

无

H3(三级标题)

仿宋_GB2312

四号 14pt

✓

左对齐

固定 28pt

无

正文

仿宋_GB2312

四号 14pt

两端对齐

固定 28pt

首行缩进 2 字符

表格

仿宋_GB2312

五号 10.5pt

居中

单倍行距

无

许可证

MIT

Available Tools

3 tools
analyze_and_suggestA

Analyze a Markdown document and generate modification suggestions.

Performs semantic analysis across six categories:

  1. Heading hierarchy — skipped levels, missing/multiple H1, long titles

  2. Required 公文 sections — expected elements in Chinese government docs

  3. Format issues — broken image references, HTML table problems

  4. Content issues — empty sections, placeholder text, duplicates, long paragraphs

  5. Numbered list continuity — gaps and restarts in ordered lists

  6. Chinese punctuation — half-width marks, missing sentence endings

Generates a structured report at <input_dir>/-修改建议.md with findings organized by category, each showing line numbers, severity, and specific suggestions.

Args: input_path: Absolute path to the input Markdown file.

Returns: Summary string with input path, suggestions file path, and issue count.

Inputs: input_path (required). Returns: result

convert_markdown_to_docxA

Convert a Markdown file to Word (.docx) with formatting.

Applies Chinese government document formatting (公文格式规范) by default:

  • Headings: 黑体 (H1 三号16pt, H2 小三15pt, H3 四号14pt) bold, left-aligned

  • Body: 仿宋_GB2312 四号14pt, justified, 2-char first-line indent

  • Tables: 仿宋_GB2312 五号10.5pt, center-aligned

  • Line spacing: fixed 28pt for body/headings, single for tables

Args: input_path: Absolute path to the input Markdown file. output_path: Output .docx path. Defaults to <input_dir>/<input_stem>.docx. format_spec: Path to a format description markdown file (like 格式要求.md). Overrides the default format. The file defines fonts, sizes, spacing, and alignment per Word style (H1/H2/H3/正文/表格). reference_docx: Path to a .docx template whose styles overlay on top of the format spec. Useful for matching an existing document's styles. extract_media: Directory to extract media files to. skip_format: If True, bypass ALL formatting (pure pandoc output). no_cache_template: If True, force regeneration of the cached reference template (needed when format spec changes). auto_suggest: If True, automatically generate a modification suggestions report (xx-修改建议.md) after conversion. The report covers heading hierarchy, required sections, format issues, content problems, list continuity, and Chinese punctuation.

Returns: Summary string with input path, output path, file size, and optionally the modification suggestions report path and issue count.

Inputs: input_path (required), format_spec, output_path, skip_format, +4 more. Returns: result

convert_markdown_to_xlsxA

Convert Markdown tables to an Excel (.xlsx) file.

Extracts every HTML and Markdown pipe table from the document (in document order) and writes each to its own worksheet. Preserves colspan/rowspan merged cells, inline bold, and text-align alignment.

Styling:

  • Font: 微软雅黑 (11pt body), thin borders on all cells

  • Header cells (HTML or the first row of a pipe table): bold + light gray fill

  • All cells: vertical center, wrap text

  • Column widths and row heights estimated from content

Args: input_path: Absolute path to the input Markdown file. output_path: Output .xlsx path. Defaults to <input_dir>/<input_stem>.xlsx. font_name: Optional font name override (default 微软雅黑). body_size: Optional body font size override (default 11).

Returns: Summary string with input path, output path, file size, and sheet count.

Inputs: input_path (required), body_size, font_name, output_path. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: converting to docx, converting to xlsx, and analyzing the document. There is no overlap or ambiguity between them.

    Naming Consistency4/5

    Two tools follow a consistent 'convert_markdown_to_*' pattern, but the third tool 'analyze_and_suggest' breaks that pattern, using a different verb structure. This minor inconsistency prevents a perfect score.

    Tool Count4/5

    Three tools is a small but reasonable set for the server's purpose. Each tool serves a clear function, and the count feels appropriate for the focused scope of Markdown-to-document conversion and analysis.

    Completeness3/5

    The server covers the core conversion to Word and Excel, plus analysis, but lacks other common output formats like PDF or HTML. For a document conversion tool, this is a notable gap, though the specialized Chinese government formatting focus partly justifies the limitation.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers