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를 참조하세요.

요구 사항

• 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 변환기 바로가기를 생성합니다. 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 서식은 굵게로 근사 처리됩니다:

이미지

• 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-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"]
    }
  }
}

노출된 도구

구성 후 다음과 같이 말할 수 있습니다:

• "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 라이선스가 적용된 다음 오픈 소스 라이브러리에 의존합니다:

전체 라이선스 텍스트는 THIRD_PARTY_NOTICES.md에 복제되어 있습니다.