Overview

This MCP (Model Context Protocol) server converts web pages (HTML) into clean, structured Markdown and is designed to work with MCP-compatible workflows. It accepts HTML (by URL or payload), parses and normalizes the document, and produces Markdown that preserves headings, lists, code blocks, tables, images and links. The service is purpose-built for developers who need reproducible, machine-friendly conversions of web content for documentation, archival, or downstream LLM processing.

A core capability is handling very large pages that would otherwise exceed model token limits. The server automatically splits large HTML documents into logical chunks, creates separate Markdown files for each chunk, and returns a manifest. This lets you feed content to LLMs or pipelines without manual chunking, while keeping the Markdown output readable and ready for static-site generators or version control.

Features

Convert HTML → CommonMark-compatible Markdown with preserved structure
Accept input by URL or raw HTML payload (POST)
Automatic chunking of very large pages to avoid token limits
Automatic file saving to disk (configurable output directory)
JSON manifest with metadata and generated filenames
CLI, HTTP API, and Docker-friendly deployment
Configurable chunking parameters (max tokens, overlap)
Optional YAML frontmatter (title, url, fetched_at)
Lightweight dependencies (Cheerio/Turndown-style pipeline) for predictable output
Logging, retry, and simple rate-limiting options for crawling scenarios

Installation / Configuration

Clone and run locally, or use the provided Docker image.

Clone and install:

git clone https://github.com/levz0r/html-to-markdown-mcp.git
cd html-to-markdown-mcp
npm install
npm run build
npm start

Run with Node (development):

npm run dev

Run in Docker (example):

docker run -p 3000:3000 \
  -e PORT=3000 \
  -e OUTPUT_DIR=/data/output \
  -e MAX_TOKENS=3000 \
  -v $(pwd)/output:/data/output \
  ghcr.io/levz0r/html-to-markdown-mcp:latest

Common environment variables / CLI options:

Variable / Flag	Default	Description
PORT	3000	HTTP server port
OUTPUT_DIR	./output	Directory where Markdown files are saved
MAX_TOKENS	2000	Approximate maximum token budget per chunk (for splitting)
CHUNK_OVERLAP	100	Token overlap between consecutive chunks to preserve context
ADD_FRONTMATTER	true	Add YAML frontmatter to generated files
VERBOSE	false	Enable verbose logging

You can pass per-request overrides in the API body (see examples below) to control chunking and filenames.

API (HTTP) — quick reference

POST /convert

Content-Type: application/json
Body (either url or html required):

{
  "url": "https://example.com/post.html",
  "html": "<!doctype html>...</html>",
  "max_tokens": 2500,
  "file_basename": "post-name",
  "add_frontmatter": true
}

Response (200):

{
  "status": "ok",
  "files": [
    "post-name.part-1.md",
    "post-name.part-2.md"
  ],
  "manifest": {
    "title": "Page Title",
    "url": "https://example.com/post.html",
    "fetched_at": "2026-04-09T12:00:00Z"
  }
}

Sample CURL (convert by URL):

curl -X POST http://localhost:3000/convert \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article","max_tokens":2000}'

Sample CURL (send raw HTML):

curl -X POST http://localhost:3000/convert \
  -H "Content-Type: text/html" \
  --data-binary @article.html

Available Resources

Source code and issue tracker: https://github.com/levz0r/html-to-markdown-mcp
CommonMark spec (for Markdown conformance): https://spec.commonmark.org
Typical parsing libraries used: Cheerio (HTML parsing) and Turndown or html-to-markdown (conversion)
MCP specification: look up your MCP client/server docs for integration patterns (server implements the MCP semantics for request/response and chunked contexts)

Use Cases

Archive web documentation: Automatically convert product docs or blog posts into Markdown repositories with YAML frontmatter; large manuals are split into multiple files for easier commits.
Prepare content for LLM prompts: Split a long web page into chunks that respect token limits and feed parts to LLMs without manual truncation or context loss.
Static-site migration: Migrate HTML pages to a static generator (Hugo/Jekyll) by converting to Markdown and preserving image references and link structure.
CI integration: Add a conversion step to CI pipelines to validate and normalize incoming HTML artifacts before publishing.
Scraping + analysis: Combine with a crawler to fetch pages, convert to Markdown, and run downstream NLP or indexing jobs.

Behavior details and best practices

Chunking is token-estimate based: the server estimates text tokens and splits at logical boundaries (headings, paragraphs) to produce coherent Markdown fragments.
Filenames: by default the server uses a sanitized basename derived from the page title or URL; parts are suffixed with .part-1.md, .part-2.md, etc.
Metadata: when enabled, each file gets YAML frontmatter with title, source URL, and fetched timestamp to help traceability.
Idempotence: repeated conversions of the same URL will overwrite files in the output directory by default; use a CI step to commit or snapshot results after conversion.
Error handling: the API returns structured error messages; large fetch failures often indicate remote rate-limiting—enable retries with exponential backoff in clients.

If you plan to integrate this into automated

MCP Server HTML to Markdown Converter