Convertidor MD-DOCX

Una herramienta de Python para la conversión bidireccional entre Markdown (.md) y Microsoft Word (.docx). Diseñada para facilitar el traslado de contenido entre documentos de Word y herramientas de IA como Claude, ChatGPT y GitHub Copilot.

Qué hace

• Convierte .md → .docx con la jerarquía de títulos correcta (Título, Título 1–9)

• Convierte .docx → .md como Markdown compatible con GitHub (GFM)

• Se ejecuta desde un sencillo acceso directo en el escritorio: no se requieren conocimientos de línea de comandos

• Maneja títulos, negrita/cursiva/tachado, listas, listas de tareas, tablas, citas, bloques de código, imágenes e hipervínculos

Consulta MarkdownSyntax.md para ver el mapeo completo de elementos y notas sobre lo que se conserva, aproxima o elimina.

Requisitos

• Windows 10/11

• Python 3.11+

• Los siguientes paquetes de Python (instalados mediante pip):

pip install markdown-it-py python-docx

Configuración

1. Clonar el repositorio

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

2. Instalar dependencias

pip install markdown-it-py python-docx

3. Crear el acceso directo en el escritorio

pip install pywin32
python create_shortcut.py

Esto crea un acceso directo de Convertidor MD-DOCX en tu escritorio de Windows. pywin32 solo es necesario para crear el acceso directo; no se requiere para ejecutar el convertidor en sí.

4. Ejecutar el convertidor

Haz doble clic en Convertidor MD-DOCX en tu escritorio. Se abrirá una ventana de consola con el siguiente mensaje:

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

Pega o escribe la ruta completa a tu archivo .md o .docx y presiona Enter. El archivo convertido se guardará en el mismo directorio con la extensión intercambiada.

También puedes ejecutarlo directamente desde la línea de comandos:

python md_docx_converter/converter.py

Notas de conversión

Jerarquía de títulos

El mapeo del nivel de título depende del contexto:

• MD → DOCX: Si hay exactamente un # en el documento, se convierte en un Título de Word. Todos los demás títulos bajan un nivel. Si hay varios títulos #, todos se convierten en Título 1 sin Título.

• DOCX → MD: Si el documento tiene un estilo de Título, se convierte en #. Todos los títulos suben en consecuencia. Si no hay Título, el Título 1 se convierte en #.

Elementos con pérdida de formato

El formato de Word que no tiene equivalente en Markdown se aproxima como negrita:

Imágenes

• DOCX → MD: Las imágenes incrustadas se extraen a una carpeta {filename}_images/ junto al archivo .md de salida.

• MD → DOCX: Las imágenes referenciadas por ruta relativa se vuelven a incrustar. Las imágenes faltantes se convierten en [imagen no encontrada: ruta].

Integración con Claude Code

Esta herramienta se integra con Claude Code ya sea como un plugin (recomendado: obtienes todo en dos comandos) o como un servidor MCP independiente (para configuración manual o Claude Desktop).

Opción A: Plugin de Claude Code (recomendado)

El plugin agrupa la configuración del servidor MCP y una habilidad /convert. Ejecuta estos dos comandos dentro de Claude Code:

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

Eso es todo: no se necesita más configuración. Después de ejecutar /reload-plugins, Claude obtiene las herramientas de conversión y puedes invocar la habilidad directamente:

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

O simplemente pregunta de forma natural: "Convierte esto a un documento de Word" y Claude usará las herramientas automáticamente.

Opción B: Solo servidor MCP (configuración manual)

Úsalo si solo quieres las herramientas MCP sin el plugin, o si estás configurando Claude Desktop en lugar de Claude Code.

Instalar el paquete:

pip install mcp-md-docx

Claude Code — registra el servidor MCP:

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

Claude Desktop — añade a %APPDATA%\Claude\claude_desktop_config.json:

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

Herramientas expuestas

Una vez configurado, puedes decir cosas como:

• "Lee report.docx y haz un resumen"

• "Convierte esto en un documento de Word y guárdalo en mi escritorio"

• "Convierte todos los puntos de la lista en notes.docx en una tabla"

Estructura del proyecto

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

Licencia

Este proyecto tiene la licencia GNU General Public License v3.0 (GPLv3). Eres libre de usar, modificar y distribuir este software, siempre que cualquier trabajo derivado también se distribuya bajo la misma licencia.

Consulta LICENSE para ver el texto completo de la licencia.

Bibliotecas de terceros

Este proyecto depende de las siguientes bibliotecas de código abierto, todas con licencia MIT:

Los textos completos de las licencias se reproducen en THIRD_PARTY_NOTICES.md.