MD-DOCX Converter
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→.docxcon la jerarquía de títulos correcta (Título, Título 1–9)Convierte
.docx→.mdcomo 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-docxConfiguración
1. Clonar el repositorio
git clone https://github.com/cjwpenner/md-docx-converter.git
cd md-docx-converter2. Instalar dependencias
pip install markdown-it-py python-docx3. Crear el acceso directo en el escritorio
pip install pywin32
python create_shortcut.pyEsto 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.pyNotas 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 |
|
Resaltado |
|
Versalitas |
|
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.mdde 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-converterEso 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.docxO 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-docxClaude Code — registra el servidor MCP:
claude mcp add md-docx-converter --transport stdio -- uvx mcp-md-docxClaude 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 |
| Lee un archivo |
| Crea un |
| Convierte un archivo |
| Convierte un archivo |
Una vez configurado, puedes decir cosas como:
"Lee
report.docxy 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.docxen 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 configLicencia
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 |
Marco de trabajo del servidor del Protocolo de Contexto de Modelo | MIT | |
Analizador de Markdown compatible con GitHub | MIT | |
Leer y escribir archivos Word | MIT |
Los textos completos de las licencias se reproducen en THIRD_PARTY_NOTICES.md.
Available Tools
4 toolsconvert_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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Convert PDF, Word, Excel, PowerPoint, e-mails and web pages to clean Markdown for LLMs.
Convert PDF, DOCX, XLSX and 25 other formats to clean Markdown for LLMs and RAG. No key or account.
Document to Markdown: convert Word, Excel, PowerPoint and PDF files to Markdown for an LLM.
Turn Markdown and AI answers into Word (.docx) with native equations, or into PDF.
Related MCP Servers
- AlicenseAqualityDmaintenanceConverts Markdown documents to professional Word documents with advanced formatting capabilities including mathematical formulas, custom styling, tables, images, headers/footers, and watermarks.483 npm14MIT
- FlicenseNot gradedqualityDmaintenanceConverts files (PDF, Word, images, etc.) to Markdown within Claude Desktop to reduce token usage.-
- AlicenseAqualityCmaintenanceConverts documents between Markdown, PDF, DOCX, and HTML locally with AI-friendly Markdown output and secure file access.6MIT
- AlicenseAqualityBmaintenanceEnables Claude to create, edit, mail-merge, convert and preview documents by driving a locally installed WordCraft engine headless, covering DOCX, PDF, ODT, RTF, HTML, Markdown and LaTeX. Supports templates, tables, images, comments, tracked changes, merge fields from CSV/XLSX/ODS, page rendering and folder-wide batch processing.11Apache 2.0