A
licenseA
qualityC
maintenanceConverts Markdown documents to professional Word documents with advanced formatting capabilities including mathematical formulas, custom styling, tables, images, headers/footers, and watermarks.
4
46 npm
13
MIT
MD-DOCX Converter
by cjwpenner
MD-DOCX 변환기
Markdown(.md)과 Microsoft Word(.docx) 간의 양방향 변환을 위한 Python 도구입니다. Word 문서와 Claude, ChatGPT, GitHub Copilot과 같은 AI 도구 간에 콘텐츠를 쉽게 이동할 수 있도록 설계되었습니다.
주요 기능
올바른 제목 계층 구조(제목, 제목 1~9)를 사용하여
.md→.docx변환깔끔한 GitHub Flavored Markdown(GFM)으로
.docx→.md변환간단한 바탕 화면 바로가기로 실행 — 명령줄 지식 불필요
제목, 굵게/기울임꼴/취소선, 목록, 작업 목록, 표, 인용문, 코드 블록, 이미지 및 하이퍼링크 처리
전체 요소 매핑과 보존, 근사치 처리 또는 삭제되는 항목에 대한 참고 사항은 MarkdownSyntax.md를 참조하세요.
Related MCP server: Document Reading and Converter Tool
요구 사항
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 변환기 바로가기를 생성합니다. pywin32는 바로가기를 만드는 데만 필요하며, 변환기 자체를 실행하는 데는 필요하지 않습니다.
4. 변환기 실행
바탕 화면에서 MD-DOCX 변환기를 더블 클릭합니다. 콘솔 창이 열리고 다음 메시지가 표시됩니다:
MD ↔ DOCX Converter
--------------------
Enter file path:.md 또는 .docx 파일의 전체 경로를 붙여넣거나 입력하고 Enter 키를 누릅니다. 변환된 파일은 확장자가 변경된 상태로 같은 디렉토리에 저장됩니다.
명령줄에서 직접 실행할 수도 있습니다:
python md_docx_converter/converter.py변환 참고 사항
제목 계층 구조
제목 수준 매핑은 컨텍스트에 따라 다릅니다:
MD → DOCX: 문서에
#이 하나만 있으면 Word 제목이 됩니다. 다른 모든 제목은 한 단계씩 아래로 이동합니다.#제목이 여러 개 있으면 모두 제목 1이 되며 제목은 없습니다.DOCX → MD: 문서에 제목 스타일이 있으면
#이 됩니다. 모든 제목은 그에 따라 한 단계씩 위로 이동합니다. 제목이 없으면 제목 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또는 자연스럽게 *"이것을 Word 문서로 변환해줘"*라고 요청하면 Claude가 자동으로 도구를 사용합니다.
옵션 B: MCP 서버 전용 (수동 설정)
플러그인 없이 MCP 도구만 원하거나 Claude Code가 아닌 Claude Desktop을 구성하는 경우 이 방법을 사용하세요.
패키지 설치:
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 텍스트로 |
| 디스크의 |
| 디스크의 |
구성 후 다음과 같이 말할 수 있습니다:
"
report.docx를 읽고 요약해줘""이것을 Word 문서로 만들어서 바탕 화면에 저장해줘"
"
notes.docx의 모든 글머리 기호를 표로 변환해줘"
프로젝트 구조
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 라이선스가 적용된 다음 오픈 소스 라이브러리에 의존합니다:
라이브러리 | 목적 | 라이선스 |
Model Context Protocol 서버 프레임워크 | 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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behaviors: output file location (saved alongside input) and return value (Markdown content). However, it doesn't mention error handling, file size limits, format compatibility, or permission requirements, leaving gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: first states core function, second adds crucial behavioral details (output location and return value). It's front-loaded with the primary purpose and efficiently covers additional context without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (file conversion), no annotations, and an output schema (which handles return values), the description is mostly complete. It covers purpose and key behaviors but lacks parameter details and some operational constraints, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It doesn't explain the 'path' parameter at all—no details on format, expected input type, or constraints. The description adds no parameter semantics beyond what the bare schema provides, failing to address the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action (convert), source format (.docx), target format (.md), and distinguishes from siblings like convert_md_file_to_docx (reverse operation) and read/write_docx (different actions). It precisely defines the tool's function without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (converting Word to Markdown) but doesn't explicitly state when to use this vs. alternatives like convert_md_file_to_docx or read_docx. It provides clear operational context but lacks explicit guidance on tool selection or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the output location behavior (saved alongside input with same name and .docx extension), which is valuable. However, it doesn't mention error handling, file size limits, formatting preservation, or authentication requirements that might be relevant for a file conversion tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. First sentence states the core purpose, second sentence provides crucial behavioral detail about output location. Perfectly front-loaded and appropriately sized for this simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values), a single parameter, and no annotations, the description is reasonably complete. It covers the conversion purpose and output location behavior. However, for a file operation tool, additional context about error conditions or limitations would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (parameter 'path' has no description in schema), so the description must compensate. While it doesn't explicitly explain the 'path' parameter, the context makes it clear this should be the path to a Markdown file. The description adds meaning by specifying the file type (.md) and the conversion outcome, though it could be more explicit about parameter expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action (convert), source format (Markdown .md file), and target format (Word .docx file). It distinguishes from sibling tools like convert_docx_file_to_md (reverse conversion) and read_docx/write_docx (different operations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (converting from Markdown to Word format). It doesn't explicitly state when not to use it or name specific alternatives, but the sibling tool names make the distinction obvious (e.g., use convert_docx_file_to_md for reverse conversion).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the tool's behavior by stating it reads and returns content as Markdown, but lacks details on error handling, file size limits, or performance aspects. It adds basic context but does not fully compensate for the absence of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by usage guidelines in the second. Both sentences are essential and waste no words, making it highly efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter) and the presence of an output schema (which handles return values), the description is mostly complete. It covers purpose and usage well but could benefit from more behavioral details like error cases or limitations to fully compensate for the lack of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It implies the 'path' parameter is for the document location but does not specify format or constraints. With only one parameter, the baseline is high, and the description adds some meaning by linking it to Word documents, though more detail would improve clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Read a Word (.docx) document') and the resource type, with a precise outcome ('return its full content as Markdown text'). It distinguishes from siblings like 'convert_docx_file_to_md' by emphasizing reading rather than conversion, and from 'write_docx' by focusing on input rather than output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('when the user asks you to read, summarise, edit, or work with a Word document'), which covers common scenarios. However, it does not specify when not to use it or mention alternatives like 'convert_docx_file_to_md' for different purposes, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| markdown | Yes | ||
| output_path | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool saves to disk (a behavioral trait) and specifies the output path format, but lacks details on error handling, file overwriting behavior, or performance characteristics. It adequately covers the core action but misses some operational nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by usage guidance and parameter specifics in three concise sentences. Each sentence adds value without redundancy, making it efficient and well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no annotations, but has an output schema), the description is mostly complete. It covers purpose, usage, and parameter semantics adequately. The output schema likely handles return values, so the description doesn't need to explain those. Minor gaps remain in behavioral details like error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It explains that 'markdown' is the input text and 'output_path' should be an absolute path ending in .docx, adding crucial semantic context beyond the bare schema. However, it doesn't detail markdown formatting support or path validation rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Convert Markdown text to a Word (.docx) document and save it to disk') and distinguishes it from siblings like 'convert_md_file_to_docx' (which likely processes files rather than text) and 'read_docx' (which reads rather than writes). It uses precise verbs and specifies the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('when the user asks you to create or save a Word document from text or Markdown content'), providing clear context for its application. It also implies differentiation from siblings by focusing on text input rather than file processing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v0.1.2- First observed
convert_docx_file_to_md - First observed
convert_md_file_to_docx - First observed
read_docx - First observed
write_docx
TDQS
A3.9/5.0
Scored across 4 tools
Disambiguation2/5
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.
Naming Consistency4/5
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.
Tool Count3/5
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.
Completeness4/5
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
ActivitySlowing
ResponsivenessNo issues
Related MCP Connectors
Use your own Word templates to convert Markdown → DOCX/PDF/HTML from any MCP-compatible AI.
Convert PDF, DOCX, HTML, and URLs to clean, LLM-ready markdown with tables preserved
Convert documents and web pages to clean Markdown: PDF, DOCX, XLSX, EPUB, scanned files, any URL.
PDF, Word, PowerPoint, Excel, HTML, EPUB to Markdown: OCR, page ranges, tables, RAG chunking
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables document conversion between PDF, DOCX, and Markdown formats to facilitate reading and editing complex files in AI tools like Claude Desktop or Cursor. It utilizes marker-pdf and pandoc to provide structured text versions of documents, helping to manage context and support unsupported file types.11-
- 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.69 npmMIT