MD-DOCX Converter
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 を参照してください。
Related MCP server: MarkltDown MCP Server
要件
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 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の書式は、太字 として近似されます:
Wordの書式 | Markdown出力 |
下線 |
|
ハイライト |
|
スモールキャップ |
|
フォントの色 | 削除(テキストは保持) |
画像
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-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 General Public License 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.
Inputs: path (required). Returns: result
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.
Inputs: path (required). Returns: result
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.
Inputs: path (required). Returns: result
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.
Inputs: markdown (required), output_path (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Convert PDF, Word, Excel, PowerPoint, e-mails and web pages to clean Markdown for LLMs.
Convert PDF, DOCX, XLSX and 25 other formats to clean Markdown for LLMs and RAG. No key or account.
Document to Markdown: convert Word, Excel, PowerPoint and PDF files to Markdown for an LLM.
Turn Markdown and AI answers into Word (.docx) with native equations, or into PDF.
Related MCP Servers
- AlicenseAqualityDmaintenanceConverts Markdown documents to professional Word documents with advanced formatting capabilities including mathematical formulas, custom styling, tables, images, headers/footers, and watermarks.483 npm14MIT
- 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.6MIT
- AlicenseAqualityBmaintenanceEnables Claude to create, edit, mail-merge, convert and preview documents by driving a locally installed WordCraft engine headless, covering DOCX, PDF, ODT, RTF, HTML, Markdown and LaTeX. Supports templates, tables, images, comments, tracked changes, merge fields from CSV/XLSX/ODS, page rendering and folder-wide batch processing.11Apache 2.0