Skip to main content
Glama
deenesjakoruzh
cjwpenner

MD-DOCX Converter

by cjwpenner
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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: 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-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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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
NameRequiredDescriptionDefault
pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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
NameRequiredDescriptionDefault
pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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
NameRequiredDescriptionDefault
markdownYes
output_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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.

  1. 4 tool updatesv0.1.2
    • First observedconvert_docx_file_to_md
    • First observedconvert_md_file_to_docx
    • First observedread_docx
    • First observedwrite_docx
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches