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.

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:

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

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:

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