Skip to main content
Glama

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-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の書式は、太字 として近似されます:

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

公開されているツール

ツール

機能

read_docx

.docx ファイルを読み込み、AIに完全なMarkdownテキストを返す

write_docx

AIが作成したMarkdownテキストから .docx を作成する

convert_md_file_to_docx

ディスク上の .md ファイルを .docx に変換する

convert_docx_file_to_md

ディスク上の .docx ファイルを .md に変換する

設定が完了すると、以下のような指示が可能になります:

  • 「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ライセンスの以下のオープンソースライブラリに依存しています:

ライブラリ

用途

ライセンス

mcp

Model Context Protocol サーバーフレームワーク

MIT

markdown-it-py

GitHub Flavored Markdown パーサー

MIT

python-docx

Word .docx ファイルの読み書き

MIT

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

Available Tools

4 tools
convert_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

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    Appeared in Searches