MD-DOCX コンバーター

Markdown (.md) と Microsoft Word (.docx) の間で双方向変換を行うためのPythonツールです。Word文書とClaude、ChatGPT、GitHub CopilotなどのAIツール間でコンテンツを簡単にやり取りできるように設計されています。

機能

• .md → .docx 変換：正しい見出し階層（タイトル、見出し1～9）を保持

• .docx → .md 変換：GitHub Flavored Markdown (GFM) 形式でクリーンに出力

• デスクトップショートカットから実行可能：コマンドラインの知識は不要

• 見出し、太字/斜体/取り消し線、リスト、タスクリスト、表、引用、コードブロック、画像、ハイパーリンクに対応

要素の対応関係や、保持・近似・削除される要素の詳細については 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 Converter ショートカットが作成されます。pywin32 はショートカット作成時のみ必要であり、コンバーター自体の実行には不要です。

4. コンバーターの実行

デスクトップ上の MD-DOCX Converter をダブルクリックします。コンソールウィンドウが開き、以下のように入力を求められます：

MD ↔ DOCX Converter
--------------------
Enter file path:

.md または .docx ファイルのフルパスを貼り付け（または入力）してEnterキーを押します。変換されたファイルは、拡張子が変更された状態で同じディレクトリに保存されます。

コマンドラインから直接実行することも可能です：

python md_docx_converter/converter.py

変換に関する注意点

見出しの階層

見出しレベルの対応はコンテキストに依存します：

• MD → DOCX: 文書内に # が1つだけ存在する場合、それはWordの タイトル になります。他のすべての見出しは1レベルずつ下がります。# 見出しが複数ある場合、それらはすべて 見出し1 となり、タイトルは設定されません。

• DOCX → MD: 文書に タイトル スタイルがある場合、それは # になります。すべての見出しはそれに応じてレベルが上がります。タイトルがない場合、見出し1 が # になります。

損失のある要素

Markdownに相当する書式がないWordの書式は、太字 として近似されます：

画像

• DOCX → MD: 埋め込み画像は、出力された .md ファイルと同じ場所にある {filename}_images/ フォルダに抽出されます。

• MD → DOCX: 相対パスで参照されている画像は再埋め込みされます。見つからない画像は [image not found: path] となります。

Claude Codeとの統合

このツールは、プラグイン（推奨：2つのコマンドですべて完了）またはスタンドアロンの MCPサーバー（手動設定やClaude Desktop用）としてClaude Codeと統合できます。

オプションA：Claude Codeプラグイン（推奨）

プラグインにはMCPサーバーの設定と /convert スキルがバンドルされています。Claude Code内で以下の2つのコマンドを実行してください：

/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 General Public License v3.0 (GPLv3) の下でライセンスされています。このソフトウェアは、派生作品も同じライセンスの下で配布される限りにおいて、自由に使用、修正、配布することができます。

ライセンスの全文については LICENSE を参照してください。

サードパーティライブラリ

本プロジェクトは、すべてMITライセンスの以下のオープンソースライブラリに依存しています：

ライセンスの全文は THIRD_PARTY_NOTICES.md に記載されています。