Todos los recursos
Guía / Instalación Free
Instala MarkItDown en Claude Code y Claude Desktop

Instala MarkItDown
en Claude Code y Claude Desktop

MarkItDown es la herramienta de Microsoft que convierte PDF, Word, Excel, PowerPoint y más a Markdown limpio. Úsalo desde Claude Code con un entorno virtual de Python, o instálalo como servidor MCP en Claude Desktop — en lugar de que Claude "vea" tus archivos como imágenes, los lee como texto plano.

Claude Code Claude Desktop MarkItDown Python
~55,000
tokens promedio para un PDF de 21 páginas
~7,700
tokens del mismo documento ya en Markdown
7–8×
menos tokens cada vez que lo usas como contexto
Por qué importa

Cuando subes un PDF directo a Claude, cada página se procesa como imagen + texto extraído — más lento y más caro. Si conviertes ese mismo archivo a .md antes de pasarlo, Claude lo lee como texto plano puro.

FormatoCómo lo procesa ClaudeTokens estimados
PDF (21 págs) Cada página se convierte en imagen + texto extraído — en la práctica ronda 2,300–3,000 tokens/página combinados ~48,000–63,000
Markdown (.md) Solo texto plano, sin overhead de imagen ~7,000–8,500
Conclusión: el .md consume aproximadamente 7 a 8 veces menos tokens que el PDF cada vez que lo usas como contexto — y Claude ya no necesita "ver" cada página como imagen.
Stack de herramientas
Fase Herramienta Rol
Fase 1 Terminal (git + venv) Clona el repo de MarkItDown y crea un entorno virtual de Python
Fase 2 Claude Code Activa el entorno y convierte tus archivos cuando se lo pides
Alternativa Claude Desktop (MCP) Instálalo como servidor MCP si prefieres la app de escritorio en vez de Claude Code
1
Clona el repo y prepara el entorno
Terminal — una sola vez

MarkItDown es una librería de Python de Microsoft. Se instala clonando el repo y creando un entorno virtual (venv) donde vive de forma aislada, sin tocar tu Python del sistema.

Terminal — clonar e instalar 
# 1. Clona el repositorio
git clone https://github.com/microsoft/markitdown.git
cd markitdown

# 2. Crea el entorno virtual
python3 -m venv .venv
source .venv/bin/activate

# 3. Instala MarkItDown en modo editable
pip install -e 'packages/markitdown[all]'
Si tu carpeta está sincronizada con iCloud Drive, Dropbox, OneDrive o Google Drive, git y la creación del entorno virtual pueden fallar con errores como "Operation not permitted" o problemas para crear archivos de bloqueo (.lock). Si ves esto, clona el repo en una carpeta local no sincronizada (por ejemplo ~/Developer o ~/proyectos) y usa esa ruta al darle acceso a Claude.
El entorno virtual no queda activado para siempre. Cada vez que abras una terminal nueva y quieras usar MarkItDown, tienes que volver a correr source .venv/bin/activate desde la carpeta del repo.
2
Actívalo y pídele a Claude Code que lo use
Cada vez que quieras convertir un archivo
1
Abre Claude Code en (o dale acceso a) la carpeta donde clonaste el repo de MarkItDown.
2
Dale el archivo que quieres convertir — arrástralo o dale la ruta — y pídele explícitamente que active el entorno virtual y lo use para convertirlo.
Ejemplo de instrucción 
Activa el entorno virtual de MarkItDown en [ruta a tu carpeta]/markitdown y úsalo para convertir [archivo.pdf] a Markdown.
Tip: guarda el .md resultante como referencia permanente del documento. Cada vez que lo vuelvas a usar como contexto, pagas 7–8 veces menos tokens que si subieras el PDF original de nuevo.
3
Verifica cuánto ahorras en tokens
Compara el peso real de tu archivo

Después de convertir tu archivo, pídele a Claude que compare el peso en tokens del PDF original contra el Markdown resultante, para que veas el ahorro real en tu caso.

Ejemplo de instrucción 
Dame el peso en tokens del archivo PDF (si Claude lo tuviera que procesar como imagen, página por página) comparado con el archivo Markdown que acabas de generar, y calcula cuántas veces menos tokens vas a usar cada vez que uses el .md como contexto en vez del PDF.
Nota: el ahorro real depende del documento. En PDFs largos y densos en texto (10+ páginas) el ahorro suele ser dramático (7–8x), porque el PDF se procesa como imagen por página. En documentos muy cortos, de una sola página, o con diseño gráfico pesado (poster, one-pager), el ahorro puede ser mucho menor o incluso no notarse, porque casi no hay overhead de imagen que evitar. No uses un one-pager como ejemplo de referencia en la guía — usa un PDF de al menos 10–15 páginas de texto para que el número sea representativo.
Alternativa
4
Instálalo en Claude Desktop
Si prefieres la app de escritorio en vez de Claude Code

En Claude Desktop, MarkItDown se conecta distinto: como servidor MCP, usando el paquete oficial markitdown-mcp. Aquí no activas un venv a mano — Claude Desktop lo ejecuta por ti a través de uv.

1
Instala uv (gestor de paquetes de Python que ejecuta el servidor MCP sin instalar nada de forma permanente).
Terminal — instalar uv (macOS) 
# Opción 1 — script oficial
curl -LsSf https://astral.sh/uv/install.sh | sh

# Opción 2 — Homebrew
brew install uv
PowerShell — instalar uv (Windows) 
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
2
No necesitas editar el JSON a mano: abre una terminal y pídele a Claude Code, en lenguaje natural, que agregue el servidor MCP de MarkItDown a tu configuración de Claude Desktop. Claude Code localiza el archivo (o lo crea) y edita el JSON por ti sin tocar los servidores que ya tengas configurados.
Ejemplo de instrucción para Claude Code 
Agrega el servidor MCP "markitdown" a mi configuración de Claude Desktop (claude_desktop_config.json — en macOS está en ~/Library/Application Support/Claude/, en Windows en %APPDATA%\Claude\). Debe usar command "uvx" y args ["markitdown-mcp"]. Si el archivo no existe, créalo; si ya tiene otros servidores dentro de mcpServers, no los borres, solo agrega esta entrada.
Así debe quedar el bloque dentro de mcpServers — Claude Code lo agrega automáticamente, esto es solo para que verifiques el resultado: 
{
  "mcpServers": {
    "markitdown": {
      "command": "uvx",
      "args": ["markitdown-mcp"]
    }
  }
}
3
Guarda el archivo y reinicia Claude Desktop por completo (ciérralo desde la barra de menú, no solo la ventana).
4
Verifica que se cargó: abre el ícono de herramientas / MCP (🔌) junto al campo de mensaje. Debe aparecer markitdown disponible.
Si no aparece: revisa que el JSON sea válido (comas, llaves) y que uvx esté en el PATH que usa la app de escritorio — en macOS a veces hace falta apuntar al binario completo, por ejemplo /Users/tuusuario/.local/bin/uvx en vez de solo uvx.
Esta vía es distinta a la de Claude Code (Fase 1, 2 y 3): aquí sí se usa uv/uvx y MCP porque es el mecanismo que usa Claude Desktop para conectar herramientas externas, mientras que Claude Code activa el entorno virtual directo desde la terminal.
Todos los recursos Ver repositorio en GitHub