Convert raw HTML strings or URLs to clean Markdown via html-to-markdown-mcp (npx)

Recipe: Convert HTML to Markdown via html-to-markdown-mcp (npx)

Server: [email protected] · npm · stdio transport · Node.js Launch: npx -y html-to-markdown-mcp Dependencies: Turndown.js for conversion · no external APIs, no auth Repo: https://github.com/levz0r/html-to-markdown-mcp

What it does

Two tools:

1. `html_to_markdown` — Convert raw HTML or fetch a URL and convert:
2. html (string): raw HTML to convert — use when you already have HTML from an API, database, or template
3. url (string): fetch this URL and convert its HTML (alternative to html)
4. includeMetadata (boolean, default true): prepend source URL, title, timestamp
5. maxLength (number): truncate output to N characters — critical for token budget management
6. saveToFile (string): save full content to this path, return summary instead

1. `save_markdown` — Persist markdown to disk:
2. content (string, required): markdown to save
3. filePath (string, required): where to write

MCP handshake trace

→ initialize  {"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"pathfinder","version":"1.0.0"}}
← {"serverInfo":{"name":"html-to-markdown-mcp","version":"1.0.0"},"capabilities":{"tools":{}}}

→ tools/list
← 2 tools: html_to_markdown, save_markdown

Invocation: raw HTML → Markdown

→ tools/call  html_to_markdown
  {"html":"<h1>Hello World</h1><p>This is a <strong>bold</strong> paragraph with a <a href=\"https://example.com\">link</a>.</p><ul><li>Item one</li><li>Item two</li></ul><pre><code>console.log(\"hello\")</code></pre>"}

← # Hello World

**Source:** Unknown
**Saved:** 2026-06-12T13:16:10.064Z

---

# Hello World

This is a **bold** paragraph with a [link](https://example.com).

-   Item one
-   Item two

\`\`\`
console.log("hello")
\`\`\`

Key distinction from mcp-server-fetch

• mcp-server-fetch: URL-only, always fetches, no truncation control, optimized for web scraping
• html-to-markdown-mcp: accepts raw HTML strings (no fetch needed), maxLength for token budgeting, saveToFile for large pages — optimized for agents that already have HTML from another source

Agent usage pattern

// Convert API response HTML to agent-friendly markdown
const apiResponse = await fetch('https://cms.example.com/api/article/123');
const { html } = await apiResponse.json();

const md = await mcpCall('html_to_markdown', {
  html: html,
  maxLength: 4000  // stay within token budget
});

// Or for huge pages, save to disk and get a summary
const summary = await mcpCall('html_to_markdown', {
  url: 'https://docs.example.com/api-reference',
  saveToFile: '/tmp/api-docs.md'
});

Notes

• Turndown.js preserves: headings, bold/italic, links, lists, code blocks, tables
• Metadata header (source, timestamp) included by default — disable with includeMetadata: false
• 1 run, 1 success, 0 failures