HTML to Markdown MCP

Obtiene páginas web y convierte HTML a Markdown limpio y formateado. Maneja páginas grandes con guardado automático de archivos para evitar límites de tokens.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP HTML a Markdown

Un servidor MCP (Protocolo de Contexto de Modelo) que convierte contenido HTML a formato Markdown usando Turndown.js.

Tabla de Contenidos

Características
Instalación
Uso
Desarrollo Local
- Pruebas
- Publicando una Nueva Versión
Seguridad
- Protección SSRF
- Permitiendo Acceso a la Red Local
Detalles Técnicos
Proyectos Relacionados
Licencia

Características

🌐 Obtener y convertir páginas web - Obtiene automáticamente HTML de cualquier URL
🔄 Convierte HTML a Markdown limpio y formateado
📝 Preserva el formato (encabezados, enlaces, bloques de código, listas, tablas)
🗑️ Elimina automáticamente elementos no deseados (scripts, estilos, etc.)
📊 Extrae automáticamente títulos de página y metadatos
⚡ Conversión rápida usando Turndown.js
🔒 Protección SSRF - Bloquea solicitudes a redes privadas/internas por defecto

Instalación

npm install -g html-to-markdown-mcp

O usa con npx (sin necesidad de instalación):

npx html-to-markdown-mcp

Uso

Con Claude Code

Agrega el servidor usando la CLI de Claude:

claude mcp add --transport stdio html-to-markdown -- npx html-to-markdown-mcp

O si está instalado globalmente:

claude mcp add --transport stdio html-to-markdown -- html-to-markdown-mcp

Con Claude Code (Plugin)

Este proyecto también se puede instalar como un plugin de Claude Code, que agrupa el servidor MCP y facilita compartirlo con equipos.

Instalar directamente desde GitHub:

/plugin marketplace add levz0r/html-to-markdown-mcp
/plugin install html-to-markdown@levz0r/html-to-markdown-mcp

O habilítalo para tu equipo agregándolo al .claude/settings.json de tu proyecto:

{
  "extraKnownMarketplaces": {
    "levz0r/html-to-markdown-mcp": {
      "source": {
        "source": "github",
        "repo": "levz0r/html-to-markdown-mcp"
      }
    }
  },
  "enabledPlugins": {
    "html-to-markdown@levz0r/html-to-markdown-mcp": true
  }
}

Con Claude Desktop

Agrega este servidor a tu archivo de configuración de Claude Desktop:

Usando npx (recomendado):

{
  "mcpServers": {
    "html-to-markdown": {
      "command": "npx",
      "args": ["html-to-markdown-mcp"]
    }
  }
}

O si está instalado globalmente:

{
  "mcpServers": {
    "html-to-markdown": {
      "command": "html-to-markdown-mcp"
    }
  }
}

Con Cursor

Agrega este servidor a tu archivo de configuración MCP de Cursor:

Usando npx (recomendado):

{
  "mcpServers": {
    "html-to-markdown": {
      "command": "npx",
      "args": ["html-to-markdown-mcp"]
    }
  }
}

O si está instalado globalmente:

{
  "mcpServers": {
    "html-to-markdown": {
      "command": "html-to-markdown-mcp"
    }
  }
}

Métodos de configuración:

A través de la Configuración de Cursor (Recomendado):
- Abre la Configuración de Cursor: ⌘ + , (macOS) o Ctrl + , (Windows/Linux)
- Navega a Archivo → Preferencias → Configuración de Cursor
- Selecciona la opción MCP
- Agrega un nuevo servidor MCP global con la configuración anterior
Edición manual de archivos:
- Global: ~/.cursor/mcp.json (disponible en todos los proyectos)
- Local: .cursor/mcp.json en el directorio de tu proyecto (específico del proyecto)

Después de agregar la configuración, reinicia Cursor para que los cambios surtan efecto.

Con Codex

Agrega este servidor a tu configuración de Codex usando la CLI o editando el archivo de configuración:

Opción 1: Usando la CLI de Codex (Recomendado):

codex mcp add html-to-markdown -- npx -y html-to-markdown-mcp

O si está instalado globalmente:

codex mcp add html-to-markdown -- html-to-markdown-mcp

Opción 2: Configuración Manual:

Edita ~/.codex/config.toml y agrega:

[mcp_servers.html-to-markdown]
command = "npx"
args = ["-y", "html-to-markdown-mcp"]

O si está instalado globalmente:

[mcp_servers.html-to-markdown]
command = "html-to-markdown-mcp"

El archivo de configuración se encuentra en ~/.codex/config.toml en todas las plataformas (macOS, Linux y Windows).

Después de actualizar la configuración, reinicia Codex o tu sesión de Codex para que los cambios surtan efecto.

Usando la Versión de Desarrollo Local

Si estás desarrollando o probando localmente, puedes agregar el servidor MCP directamente desde tu código local:

Con Claude Code:

claude mcp add --transport stdio html-to-markdown -- node /absolute/path/to/html-to-markdown-mcp/index.js

Con Claude Desktop:

{
  "mcpServers": {
    "html-to-markdown": {
      "command": "node",
      "args": ["/absolute/path/to/html-to-markdown-mcp/index.js"]
    }
  }
}

Reemplaza /absolute/path/to/html-to-markdown-mcp con la ruta real a tu repositorio clonado.

Herramientas Disponibles

`html_to_markdown`

Obtiene HTML de una URL o convierte contenido HTML proporcionado a formato Markdown. Esta herramienta es utilizada automáticamente por Claude siempre que se necesite obtener y convertir HTML.

Parámetros:

url (cadena): URL para obtener y convertir (se requiere url o html)
html (cadena): Contenido HTML crudo para convertir (se requiere url o html)
includeMetadata (booleano, opcional): Incluir encabezado de metadatos (predeterminado: true)
maxLength (número, opcional): Longitud máxima del contenido devuelto en caracteres. El contenido que exceda esto se truncará con un mensaje. Útil para páginas grandes para evitar límites de tokens.
saveToFile (cadena, opcional): Ruta de archivo para guardar el contenido completo. Cuando se especifica, guarda el markdown completo y devuelve solo un resumen. Recomendado para páginas muy grandes.

Ejemplo 1: Obtener desde URL (Recomendado)

{
  "url": "https://example.com"
}

Ejemplo 2: Convertir HTML crudo

{
  "html": "<h1>Hello World</h1><p>This is a <strong>test</strong>.</p>"
}

Ejemplo 3: Obtener página grande y guardar directamente en archivo

{
  "url": "https://www.docuseal.com/docs/api",
  "saveToFile": "./docuseal-api.md"
}

Ejemplo 4: Limitar la longitud del contenido devuelto

{
  "url": "https://example.com",
  "maxLength": 5000
}

Salida:

# Example Domain

**Source:** https://example.com
**Saved:** 2025-10-09T12:00:00.000Z

---

# Example Domain

This domain is for use in illustrative examples...

`save_markdown`

Guarda contenido markdown en un archivo en disco. Usa esto para persistir HTML convertido o cualquier contenido markdown.

Parámetros:

content (cadena, requerido): El contenido markdown a guardar
filePath (cadena, requerido): La ruta del archivo donde se debe guardar el markdown (puede ser relativa o absoluta)

Ejemplo:

{
  "content": "# My Document\n\nThis is some markdown content.",
  "filePath": "./output/document.md"
}

Uso: Puedes encadenar ambas herramientas juntas - primero convierte HTML a markdown, luego guarda el resultado en un archivo.

¿Cuándo se activa?

El servidor MCP será utilizado automáticamente por Claude cuando:

Pidas obtener información de una página web
Solicites convertir HTML a Markdown
Necesites extraer contenido de una URL
Pidas resumir o analizar una página web
Solicites guardar contenido markdown en un archivo

Ejemplos de solicitudes que lo activan:

"¿Qué hay en https://example.com?"
"Obtén y resume este artículo: https://..."
"Convierte esta página web a Markdown"
"Extrae el contenido principal de esta URL"
"Guarda esta página web como un archivo markdown"
"Obtén https://example.com y guárdalo en article.md"

Desarrollo Local

Si quieres contribuir o modificar el servidor:

# Clone the repository
git clone https://github.com/levz0r/html-to-markdown-mcp.git
cd html-to-markdown-mcp

# Install dependencies
npm install

# Run the server
npm start

Pruebas

Ejecuta el conjunto de pruebas usando el ejecutor de pruebas integrado de Node:

# Run all tests
npm test

# Run tests in watch mode (re-runs on file changes)
npm run test:watch

El conjunto de pruebas incluye:

Pruebas de descubrimiento de herramientas
Pruebas de conversión de HTML a markdown
Pruebas de obtención de URL
Pruebas de guardado de archivos
Pruebas de truncamiento y manejo de páginas grandes
Pruebas de protección SSRF
Pruebas de flujo de trabajo de integración

Publicando una Nueva Versión

El proyecto utiliza CI/CD automatizado para publicar en npm:

Actualiza la versión usando los scripts de versión de npm:

npm run version:patch  # 1.0.0 -> 1.0.1
npm run version:minor  # 1.0.0 -> 1.1.0
npm run version:major  # 1.0.0 -> 2.0.0

Empuja la etiqueta para activar la publicación automatizada:
```
git push && git push --tags
```
GitHub Actions automáticamente:
- Ejecutará todas las pruebas
- Publicará en npm si las pruebas pasan
- Agregará información de procedencia al paquete

Publicación manual (si es necesario):

npm run release:patch --otp=<code>
npm run release:minor --otp=<code>
npm run release:major --otp=<code>

Seguridad

Protección SSRF

Por defecto, el servidor bloquea solicitudes de URL a direcciones de red privadas e internas para prevenir ataques de Falsificación de Solicitudes del Lado del Servidor (SSRF). Esto incluye:

Direcciones de bucle local (127.0.0.0/8, ::1)
Redes privadas (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
Puntos finales de enlace local / metadatos de nube (169.254.0.0/16)
Esquemas no HTTP(S) (file://, ftp://, etc.)

Se verifica la resolución DNS para prevenir la evasión mediante nombres de host que resuelven a IPs privadas.

Permitiendo Acceso a la Red Local

Si necesitas convertir HTML desde servidores locales o internos (por ejemplo, un servidor de desarrollo local), puedes optar por habilitarlo con la bandera --allow-local o la variable de entorno ALLOW_LOCAL_NETWORK:

# Via CLI flag
npx html-to-markdown-mcp --allow-local

# Via environment variable
ALLOW_LOCAL_NETWORK=true npx html-to-markdown-mcp

Configuración de Claude Desktop / Cursor con acceso local:

{
  "mcpServers": {
    "html-to-markdown": {
      "command": "npx",
      "args": ["html-to-markdown-mcp", "--allow-local"]
    }
  }
}

Advertencia: Solo habilita el acceso a la red local si confías en las entradas de URL del agente de IA. Con esta bandera habilitada, el servidor puede alcanzar servicios internos, puertos de localhost y puntos finales de metadatos de nube.

Detalles Técnicos

Protocolo: Protocolo de Contexto de Modelo (MCP)
Biblioteca de Conversión: Turndown.js
Transporte: stdio
Node.js: Módulos ES

Proyectos Relacionados

Este servidor utiliza el mismo enfoque de conversión que markdown-printer, una extensión de navegador para guardar páginas web como archivos Markdown.

Licencia

MIT