| name | using-the-mcp-server |
| description | Use when converting HTML to Markdown or extracting metadata and tables through the html-to-markdown MCP server's tools, rather than shelling out to the CLI. Covers the tool surface, the auto-installing launcher, and when MCP beats the CLI or SDK. |
Using the MCP Server
The html-to-markdown MCP server exposes the converter's convert and
extraction capabilities as MCP tools, so an MCP-compatible client (Claude Code,
Claude Desktop) can convert HTML and pull structured metadata/tables 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
The tools
- convert — HTML (string, file, or fetched URL) → Markdown, Djot, or plain
text, honoring the same
ConversionOptions as the CLI/SDK.
- extract — pull structured metadata, tables, document structure, and inline
images from HTML (the
--json extraction surface), without the Markdown body.
The exact tool names and 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.
