Convert HTML, files, and data URIs to clean markdown via markitdown-mcp (uvx)

Recipe: Convert any file/URL/HTML to markdown via markitdown-mcp

Launch

uvx markitdown-mcp

Transport: stdio. Server: markitdown v1.8.1 (Microsoft MarkItDown). One tool: convert_to_markdown.

Tool inventory

Verified: Local HTML file → markdown (file: URI)

Input: An HTML page with headings, lists, bold, a table, and a link.

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"convert_to_markdown","arguments":{"uri":"file:///tmp/pathfinder-test.html"}}}

Response:

{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"# Release Notes v2.5\n\n## New Features\n\n* **Dark mode** — toggle in settings\n* **CSV export** — download any table as .csv\n\n## Bug Fixes\n\n| Issue | Status | Impact |\n| --- | --- | --- |\n| #1234 | Fixed | High |\n| #1256 | Fixed | Medium |\n\nSee [full docs](https://docs.example.com) for migration guide."}],"isError":false}}

Verified: Inline HTML → markdown (data: URI)

No file on disk needed — pass HTML as a base64 data URI.

{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"convert_to_markdown","arguments":{"uri":"data:text/html;base64,PGgxPkhlbGxvPC9oMT48cD5BIHBhcmFncmFwaCB3aXRoIDxhIGhyZWY9Imh0dHBzOi8vZXhhbXBsZS5jb20iPmEgbGluazwvYT4gYW5kIDxjb2RlPmlubGluZSBjb2RlPC9jb2RlPi48L3A+"}}}

Response:

{"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"# Hello\n\nA paragraph with [a link](https://example.com) and `inline code`."}],"isError":false}}

Notes

• Cold start: ~4s via uvx (Python install)
• Conversion quality: Excellent. Headings, bold, links, code, and tables all render correctly as GitHub-flavored markdown.
• data: URI trick: Useful when you have raw HTML as a string — base64-encode it as data:text/html;base64,... and pass directly. No temp file needed.
• Supported formats: HTML files, PDF, DOCX, PPTX, XLSX, images (via OCR), remote URLs — all through the same uri parameter.
• vs magicconvert-mcp-server: MarkItDown is backed by Microsoft's open-source engine; magicconvert uses a different stack. Both produce markdown, but MarkItDown's table rendering is cleaner and it supports data: URIs natively.
• vs mcp-server-fetch: Fetch downloads + converts to markdown; MarkItDown accepts any URI type including local files and inline data. Use MarkItDown when you already have the content locally.