HTML to Markdown MCP

Busca páginas da web e converte HTML em Markdown limpo e formatado. Lida com páginas grandes com salvamento automático de arquivos para contornar limites de tokens.

GitHub
25
Experimente este MCPPatrocinado

Documentação

Servidor MCP HTML para Markdown

npm version npm downloads

Um servidor MCP (Model Context Protocol) que converte conteúdo HTML para o formato Markdown usando Turndown.js.

Sumário

Recursos

  • 🌐 Buscar e converter páginas da web - Busca automaticamente HTML de qualquer URL
  • 🔄 Converte HTML em Markdown limpo e formatado
  • 📝 Preserva a formatação (cabeçalhos, links, blocos de código, listas, tabelas)
  • 🗑️ Remove automaticamente elementos indesejados (scripts, estilos, etc.)
  • 📊 Extrai automaticamente títulos e metadados da página
  • ⚡ Conversão rápida usando Turndown.js
  • 🔒 Proteção SSRF - Bloqueia solicitações para redes privadas/internas por padrão

Instalação

npm install -g html-to-markdown-mcp

Ou use com npx (sem necessidade de instalação):

npx html-to-markdown-mcp

Uso

Com Claude Code

Adicione o servidor usando a CLI do Claude:

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

Ou se instalado globalmente:

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

Com Claude Code (Plugin)

Este projeto também pode ser instalado como um plugin do Claude Code, que agrupa o servidor MCP e facilita o compartilhamento com equipes.

Instale diretamente do GitHub:

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

Ou habilite para sua equipe adicionando ao .claude/settings.json do seu projeto:

{
  "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
  }
}

Com Claude Desktop

Adicione este servidor ao seu arquivo de configuração do Claude Desktop:

Usando npx (recomendado):

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

Ou se instalado globalmente:

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

Com Cursor

Adicione este servidor ao seu arquivo de configurações MCP do Cursor:

Usando npx (recomendado):

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

Ou se instalado globalmente:

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

Métodos de configuração:

  1. Via Configurações do Cursor (Recomendado):

    • Abra as Configurações do Cursor: ⌘ + , (macOS) ou Ctrl + , (Windows/Linux)
    • Navegue até Arquivo → Preferências → Configurações do Cursor
    • Selecione a opção MCP
    • Adicione um novo servidor MCP global com a configuração acima

  2. Edição manual do arquivo:

    • Global: ~/.cursor/mcp.json (disponível em todos os projetos)
    • Local: .cursor/mcp.json no diretório do seu projeto (específico do projeto)

Após adicionar a configuração, reinicie o Cursor para que as alterações tenham efeito.

Com Codex

Adicione este servidor à sua configuração do Codex usando a CLI ou editando o arquivo de configuração:

Opção 1: Usando a CLI do Codex (Recomendado):

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

Ou se instalado globalmente:

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

Opção 2: Configuração Manual:

Edite ~/.codex/config.toml e adicione:

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

Ou se instalado globalmente:

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

O arquivo de configuração está localizado em ~/.codex/config.toml em todas as plataformas (macOS, Linux e Windows).

Após atualizar a configuração, reinicie o Codex ou sua sessão do Codex para que as alterações tenham efeito.

Usando a Versão de Desenvolvimento Local

Se você está desenvolvendo ou testando localmente, pode adicionar o servidor MCP diretamente do seu código local:

Com Claude Code:

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

Com Claude Desktop:

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

Substitua /absolute/path/to/html-to-markdown-mcp pelo caminho real para o seu repositório clonado.

Ferramentas Disponíveis

html_to_markdown

Busca HTML de uma URL ou converte o conteúdo HTML fornecido para o formato Markdown. Esta ferramenta é usada automaticamente pelo Claude sempre que HTML precisa ser buscado e convertido.

Parâmetros:

  • url (string): URL para buscar e converter (url ou html é obrigatório)
  • html (string): Conteúdo HTML bruto para converter (url ou html é obrigatório)
  • includeMetadata (booleano, opcional): Incluir cabeçalho de metadados (padrão: true)
  • maxLength (número, opcional): Comprimento máximo do conteúdo retornado em caracteres. Conteúdo que exceder isso será truncado com uma mensagem. Útil para páginas grandes para evitar limites de tokens.
  • saveToFile (string, opcional): Caminho do arquivo para salvar o conteúdo completo. Quando especificado, salva o markdown completo e retorna apenas um resumo. Recomendado para páginas muito grandes.

Exemplo 1: Buscar da URL (Recomendado)

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

Exemplo 2: Converter HTML bruto

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

Exemplo 3: Buscar página grande e salvar diretamente em arquivo

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

Exemplo 4: Limitar o comprimento do conteúdo retornado

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

Saída:

# 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

Salva conteúdo markdown em um arquivo no disco. Use isso para persistir HTML convertido ou qualquer conteúdo markdown.

Parâmetros:

  • content (string, obrigatório): O conteúdo markdown para salvar
  • filePath (string, obrigatório): O caminho do arquivo onde o markdown deve ser salvo (pode ser relativo ou absoluto)

Exemplo:

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

Uso: Você pode encadear ambas as ferramentas - primeiro converta HTML para markdown, depois salve o resultado em um arquivo.

Quando ele é ativado?

O servidor MCP será usado automaticamente pelo Claude quando você:

  • Pedir para buscar informações de uma página da web
  • Solicitar a conversão de HTML para Markdown
  • Precisar extrair conteúdo de uma URL
  • Pedir para resumir ou analisar uma página da web
  • Solicitar para salvar conteúdo markdown em um arquivo

Exemplos de prompts que o ativam:

  • "O que há em https://example.com?"
  • "Busque e resuma este artigo: https://..."
  • "Converta esta página da web para Markdown"
  • "Extraia o conteúdo principal desta URL"
  • "Salve esta página da web como um arquivo markdown"
  • "Busque https://example.com e salve em article.md"

Desenvolvimento Local

Se você quiser contribuir ou modificar o 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

Testes

Execute a suíte de testes usando o executor de testes integrado do Node:

# Run all tests
npm test

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

A suíte de testes inclui:

  • Testes de descoberta de ferramentas
  • Testes de conversão de HTML para markdown
  • Testes de busca de URL
  • Testes de salvamento de arquivos
  • Testes de truncamento e manipulação de páginas grandes
  • Testes de proteção SSRF
  • Testes de fluxo de trabalho de integração

Publicando uma Nova Versão

O projeto usa CI/CD automatizado para publicação no npm:

  1. Atualize a versão usando os scripts de versão do 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

  2. Envie a tag para acionar a publicação automatizada:

    git push && git push --tags

  3. GitHub Actions automaticamente:

    • Executará todos os testes
    • Publicará no npm se os testes passarem
    • Adicionará informações de proveniência ao pacote

Publicação manual (se necessário):

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

Segurança

Proteção SSRF

Por padrão, o servidor bloqueia solicitações de URL para endereços de rede privados e internos para prevenir ataques de Server-Side Request Forgery (SSRF). Isso inclui:

  • Endereços de loopback (127.0.0.0/8, ::1)
  • Redes privadas (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
  • Endpoints de link-local / metadados de nuvem (169.254.0.0/16)
  • Esquemas não-HTTP(S) (file://, ftp://, etc.)

A resolução de DNS é verificada para prevenir bypass via nomes de host que resolvem para IPs privados.

Permitindo Acesso à Rede Local

Se você precisar converter HTML de servidores locais ou internos (por exemplo, um servidor de desenvolvimento local), você pode optar por ativar com a flag --allow-local ou a variável de ambiente 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

Configuração do Claude Desktop / Cursor com acesso local:

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

Aviso: Só habilite o acesso à rede local se você confiar nas entradas de URL do agente de IA. Com esta flag habilitada, o servidor pode alcançar serviços internos, portas localhost e endpoints de metadados de nuvem.

Detalhes Técnicos

  • Protocolo: Model Context Protocol (MCP)
  • Biblioteca de Conversão: Turndown.js
  • Transporte: stdio
  • Node.js: Módulos ES

Projetos Relacionados

Este servidor usa a mesma abordagem de conversão do markdown-printer, uma extensão de navegador para salvar páginas da web como arquivos Markdown.

Licença

MIT