Skip to main content
Glama

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.

Related MCP server: MarkltDown MCP Server

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:

Formato de Word

Salida Markdown

Subrayado

**negrita**

Resaltado

**negrita**

Versalitas

**negrita**

Color de fuente

Eliminado (se mantiene el texto)

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

Herramienta

Qué hace

read_docx

Lee un archivo .docx: devuelve el texto Markdown completo a la IA

write_docx

Crea un .docx a partir del texto Markdown que la IA ha escrito

convert_md_file_to_docx

Convierte un archivo .md en disco a .docx

convert_docx_file_to_md

Convierte un archivo .docx en disco a .md

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:

Biblioteca

Propósito

Licencia

mcp

Marco de trabajo del servidor del Protocolo de Contexto de Modelo

MIT

markdown-it-py

Analizador de Markdown compatible con GitHub

MIT

python-docx

Leer y escribir archivos Word .docx

MIT

Los textos completos de las licencias se reproducen en 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