Using the MCP Server
The html-to-markdown MCP server exposes the converter's conversion and
metadata-extraction capabilities as MCP tools, so an MCP-compatible client (Claude
Code, Claude Desktop) can convert HTML and pull structured metadata directly,
with no CLI invocation or glue code.
How it runs in this plugin
The plugin auto-registers the server. Its command is the bundled launcher
scripts/mcp-launch.sh, which execs html-to-markdown mcp. On first run the
launcher resolves an html-to-markdown binary: it reuses one already on PATH
or cached in the plugin's bin/, then tries npx/uvx, then Homebrew, then
downloads a prebuilt from the tool's latest GitHub release. Override the channel
with HTML_TO_MARKDOWN_LAUNCHER=auto|npx|uvx|brew|download.
The mcp subcommand ships in a recent release of the tool. If an older
html-to-markdown is already on PATH, it may not expose mcp yet — upgrade
the binary (brew upgrade, re-download, or rebuild) to pick it up.
To run it manually:
html-to-markdown mcp # for Claude Code / Claude Desktop (stdio)
The tools
- convert_html — convert an HTML string to Markdown, Djot, or plain text.
Takes
html (the HTML string), an optional config object mirroring
ConversionOptions, and an optional json flag. With json: true it returns
the full ConversionResult (content, tables, metadata, document structure,
inline images, warnings) instead of the bare converted text.
- extract_metadata — pull structured metadata (document info, Open
Graph / Twitter / JSON-LD / Microdata, headers, links, images) from an HTML
string. Takes only
html.
Both tools accept an HTML string — the MCP server does not fetch URLs or read
files (that is CLI-only). The exact argument schemas come from the running
server; ask the client to list tools to see the live surface.
When to prefer MCP over the CLI or SDK
- Prefer MCP inside an agent session: the agent calls the converter directly
as a tool, with no shell-out and no process management.
- Prefer the CLI for one-shot conversions and shell pipelines (
… | jq).
- Prefer the SDK when embedding conversion in application code.
1---2name: using-the-mcp-server-113description: >-4 Use when converting HTML to Markdown or extracting metadata and tables5 through the html-to-markdown MCP server's tools, rather than shelling out to6 the CLI. Covers the tool surface, the auto-installing launcher, and when MCP7 beats the CLI or SDK.8metadata:9 source: https://skillmd.com/skills/kreuzberg-dev/using-the-mcp-server-1110---1112<!--13AI-RULEZ :: GENERATED FILE — DO NOT EDIT14Content-Hash: blake3:c6276d5c9515b3ea110d1f483a3c0ac259c4edb0b9e298431f5644d1c4103c6615Source-Hash: blake3:2a98a70a27241d0cbaa39fff18410711494d4759d9c0cdb3630d4ac0d2144c7516Schema-Version: v117-->1819# Using the MCP Server2021The `html-to-markdown` MCP server exposes the converter's conversion and22metadata-extraction capabilities as MCP tools, so an MCP-compatible client (Claude23Code, Claude Desktop) can convert HTML and pull structured metadata directly,24with no CLI invocation or glue code.2526## How it runs in this plugin2728The plugin auto-registers the server. Its command is the bundled launcher29`scripts/mcp-launch.sh`, which execs `html-to-markdown mcp`. On first run the30launcher resolves an `html-to-markdown` binary: it reuses one already on `PATH`31or cached in the plugin's `bin/`, then tries `npx`/`uvx`, then Homebrew, then32downloads a prebuilt from the tool's latest GitHub release. Override the channel33with `HTML_TO_MARKDOWN_LAUNCHER=auto|npx|uvx|brew|download`.3435The `mcp` subcommand ships in a recent release of the tool. If an older36`html-to-markdown` is already on `PATH`, it may not expose `mcp` yet — upgrade37the binary (`brew upgrade`, re-download, or rebuild) to pick it up.3839To run it manually:4041```bash42html-to-markdown mcp # for Claude Code / Claude Desktop (stdio)43```4445## The tools4647- **convert_html** — convert an HTML string to Markdown, Djot, or plain text.48 Takes `html` (the HTML string), an optional `config` object mirroring49 `ConversionOptions`, and an optional `json` flag. With `json: true` it returns50 the full `ConversionResult` (content, tables, metadata, document structure,51 inline images, warnings) instead of the bare converted text.52- **extract_metadata** — pull structured metadata (document info, Open53 Graph / Twitter / JSON-LD / Microdata, headers, links, images) from an HTML54 string. Takes only `html`.5556Both tools accept an HTML **string** — the MCP server does not fetch URLs or read57files (that is CLI-only). The exact argument schemas come from the running58server; ask the client to list tools to see the live surface.5960## When to prefer MCP over the CLI or SDK6162- **Prefer MCP** inside an agent session: the agent calls the converter directly63 as a tool, with no shell-out and no process management.64- **Prefer the CLI** for one-shot conversions and shell pipelines (`… | jq`).65- **Prefer the SDK** when embedding conversion in application code.