Skip to main content
Glama

MD-DOCX Konverter

Ein Python-Tool für die bidirektionale Konvertierung zwischen Markdown (.md) und Microsoft Word (.docx). Entwickelt, um den Austausch von Inhalten zwischen Word-Dokumenten und KI-Tools wie Claude, ChatGPT und GitHub Copilot zu erleichtern.

Funktionsweise

  • Konvertiert .md → .docx mit korrekter Überschriftenhierarchie (Titel, Überschrift 1–9)

  • Konvertiert .docx → .md als sauberes GitHub Flavored Markdown (GFM)

  • Läuft über eine einfache Desktop-Verknüpfung — keine Kenntnisse der Befehlszeile erforderlich

  • Unterstützt Überschriften, Fett-/Kursiv-/Durchgestrichen-Formatierung, Listen, Aufgabenlisten, Tabellen, Blockzitate, Code-Blöcke, Bilder und Hyperlinks

Siehe MarkdownSyntax.md für die vollständige Elementzuordnung und Hinweise dazu, was beibehalten, angenähert oder verworfen wird.

Related MCP server: MarkltDown MCP Server

Anforderungen

  • Windows 10/11

  • Python 3.11+

  • Die folgenden Python-Pakete (installiert via pip):

pip install markdown-it-py python-docx

Einrichtung

1. Repository klonen

git clone https://github.com/cjwpenner/md-docx-converter.git
cd md-docx-converter

2. Abhängigkeiten installieren

pip install markdown-it-py python-docx

3. Desktop-Verknüpfung erstellen

pip install pywin32
python create_shortcut.py

Dies erstellt eine MD-DOCX Konverter-Verknüpfung auf Ihrem Windows-Desktop. pywin32 wird nur zum Erstellen der Verknüpfung benötigt — es ist nicht erforderlich, um den Konverter selbst auszuführen.

4. Konverter ausführen

Doppelklicken Sie auf MD-DOCX Konverter auf Ihrem Desktop. Ein Konsolenfenster öffnet sich und fordert Sie auf:

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

Fügen Sie den vollständigen Pfad zu Ihrer .md- oder .docx-Datei ein oder geben Sie ihn ein und drücken Sie die Eingabetaste. Die konvertierte Datei wird im selben Verzeichnis mit der entsprechenden Dateiendung gespeichert.

Sie können das Programm auch direkt über die Befehlszeile ausführen:

python md_docx_converter/converter.py

Hinweise zur Konvertierung

Überschriftenhierarchie

Die Zuordnung der Überschriftenebenen ist kontextabhängig:

  • MD → DOCX: Wenn es genau ein # im Dokument gibt, wird es zu einem Word-Titel. Alle anderen Überschriften werden um eine Ebene nach unten verschoben. Wenn es mehrere #-Überschriften gibt, werden alle zu Überschrift 1 ohne Titel.

  • DOCX → MD: Wenn das Dokument ein Titel-Format hat, wird es zu #. Alle Überschriften werden entsprechend nach oben verschoben. Wenn kein Titel vorhanden ist, wird Überschrift 1 zu #.

Verlustbehaftete Elemente

Word-Formatierungen, die kein Markdown-Äquivalent haben, werden als fett angenähert:

Word-Formatierung

Markdown-Ausgabe

Unterstrichen

**fett**

Hervorhebung

**fett**

Kapitälchen

**fett**

Schriftfarbe

Entfernt (Text bleibt erhalten)

Bilder

  • DOCX → MD: Eingebettete Bilder werden in einen {filename}_images/-Ordner neben der ausgegebenen .md-Datei extrahiert.

  • MD → DOCX: Bilder, auf die über einen relativen Pfad verwiesen wird, werden neu eingebettet. Fehlende Bilder werden zu [image not found: path].

Claude Code Integration

Dieses Tool lässt sich in Claude Code entweder als Plugin (empfohlen — erledigt alles mit zwei Befehlen) oder als eigenständiger MCP-Server (für manuelle Einrichtung oder Claude Desktop) integrieren.

Option A: Claude Code Plugin (empfohlen)

Das Plugin bündelt die MCP-Server-Konfiguration und eine /convert-Fähigkeit. Führen Sie diese beiden Befehle innerhalb von Claude Code aus:

/plugin marketplace add cjwpenner/md-docx-converter
/plugin install md-docx-converter@md-docx-converter

Das ist alles — keine weitere Konfiguration erforderlich. Nach dem Ausführen von /reload-plugins erhält Claude die Konvertierungstools und Sie können die Fähigkeit direkt aufrufen:

/md-docx-converter:convert path/to/file.md
/md-docx-converter:convert path/to/report.docx

Oder fragen Sie einfach natürlich: "Konvertiere dies in ein Word-Dokument" und Claude wird die Tools automatisch verwenden.

Option B: Nur MCP-Server (manuelle Einrichtung)

Verwenden Sie dies, wenn Sie nur die MCP-Tools ohne das Plugin wünschen oder wenn Sie Claude Desktop anstelle von Claude Code konfigurieren.

Paket installieren:

pip install mcp-md-docx

Claude Code — MCP-Server registrieren:

claude mcp add md-docx-converter --transport stdio -- uvx mcp-md-docx

Claude Desktop — Hinzufügen zu %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "md-docx-converter": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-md-docx"]
    }
  }
}

Verfügbare Tools

Tool

Funktionsweise

read_docx

Liest eine .docx-Datei — gibt den vollständigen Markdown-Text an die KI zurück

write_docx

Erstellt ein .docx aus dem von der KI geschriebenen Markdown-Text

convert_md_file_to_docx

Konvertiert eine .md-Datei auf der Festplatte in .docx

convert_docx_file_to_md

Konvertiert eine .docx-Datei auf der Festplatte in .md

Nach der Konfiguration können Sie Dinge sagen wie:

  • "Lies report.docx und fasse es zusammen"

  • "Wandle dies in ein Word-Dokument um und speichere es auf meinem Desktop"

  • "Konvertiere alle Aufzählungspunkte in notes.docx in eine Tabelle"

Projektstruktur

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

Lizenz

Dieses Projekt ist unter der GNU General Public License v3.0 (GPLv3) lizenziert. Sie können diese Software frei verwenden, ändern und verbreiten, vorausgesetzt, dass alle abgeleiteten Werke ebenfalls unter derselben Lizenz verbreitet werden.

Siehe LICENSE für den vollständigen Lizenztext.

Bibliotheken von Drittanbietern

Dieses Projekt hängt von den folgenden Open-Source-Bibliotheken ab, die alle unter der MIT-Lizenz stehen:

Bibliothek

Zweck

Lizenz

mcp

Model Context Protocol Server-Framework

MIT

markdown-it-py

GitHub Flavored Markdown Parser

MIT

python-docx

Lesen und Schreiben von Word .docx-Dateien

MIT

Die vollständigen Lizenztexte sind in THIRD_PARTY_NOTICES.md wiedergegeben.

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