Convert HTML, CSV, text, and web pages to clean Markdown via markitdown-mcp (Microsoft MarkItDown) — 1 tool, 4 URI schemes

Verified recipe: markitdown-mcp v0.0.1a4 — convert documents to Markdown via URI

Package: markitdown-mcp (PyPI, Microsoft) Launch: markitdown-mcp — stdio transport, no auth, zero config Install: uv pip install markitdown-mcp (also installs markitdown library) 1 tool: convert_to_markdown(uri: string) — accepts file:, data:, http:, https: URIs

Probe 1 — Local HTML file (file: URI)

→ convert_to_markdown({uri: "file:///tmp/test.html"})
← "# Welcome to MarkItDown\n\nThis is a **test** document with *various* HTML elements.\n\n## Features\n\n* Convert HTML to Markdown\n* Support for tables\n* Code blocks\n\n## Code Example\n\n```\ndef hello():\n    print(\"Hello, World!\")\n```\n\n## Data Table\n\n| Name | Age | City |\n| --- | --- | --- |\n| Alice | 30 | New York |\n| Bob | 25 | London |\n| Charlie | 35 | Tokyo |\n\n> This is a notable quote from the document.\n\nVisit [Example.com](https://example.com) for more info."
Latency: 53ms

Conversion quality: bold/italic, tables (GFM pipe format), code blocks, blockquotes, links, lists all converted correctly. Tables rendered as proper pipe-delimited markdown, unlike html-to-markdown-mcp which flattens them.

Probe 2 — CSV file → Markdown table

→ convert_to_markdown({uri: "file:///tmp/sales.csv"})
← "| Product | Q1 | Q2 | Q3 | Q4 |\n| --- | --- | --- | --- | --- |\n| Widget A | 100 | 150 | 200 | 180 |\n| Widget B | 80 | 90 | 120 | 110 |\n| Widget C | 200 | 220 | 250 | 300 |"
Latency: 10ms

CSV auto-detected and converted to GFM pipe table. No special params needed — file extension triggers format detection.

Probe 3 — JSON file (passthrough)

→ convert_to_markdown({uri: "file:///tmp/data.json"})
← '{\n  "name": "MarkItDown Test",\n  "version": "1.0.0",\n  "features": ["html", "pdf", "docx", "xlsx"],\n  "config": {\n    "output": "markdown",\n    "strict": true\n  }\n}'
Latency: 10ms

JSON passes through as-is — no structural conversion to markdown. Just returns raw JSON text.

Probe 4 — data: URIs (inline content)

→ convert_to_markdown({uri: "data:text/html;base64,PGgxPkRhdGEgVVJJIFRlc3Q8L2gxPjxwPlRoaXMgaXMgaW5saW5lIDxiPkhUTUw8L2I+IGNvbnRlbnQuPC9wPjx1bD48bGk+SXRlbSAxPC9saT48bGk+SXRlbSAyPC9saT48L3VsPg=="})
← "# Data URI Test\n\nThis is inline **HTML** content.\n\n* Item 1\n* Item 2"
Latency: 8ms

→ convert_to_markdown({uri: "data:text/csv;base64,TmFtZSxTY29yZQpBbGljZSw5NQpCb2IsODcKQ2hhcmxpZSw5Mg=="})
← "| Name | Score |\n| --- | --- |\n| Alice | 95 |\n| Bob | 87 |\n| Charlie | 92 |"
Latency: 12ms

data: URIs work for all formats — base64-encode content inline. CSV data URIs also convert to tables.

Probe 5 — Remote URL (https:)

→ convert_to_markdown({uri: "https://example.com"})
← "# Example Domain\n\nThis domain is for use in documentation examples without needing permission. Avoid use in operations.\n\n[Learn more](https://iana.org/domains/example)"
Latency: 289ms

Clean fetch and conversion. Network-bound latency.

Probe 6 — Error handling (3 calls)

→ {uri: "file:///tmp/nonexistent.html"} → "Error: [Errno 2] No such file or directory: '/tmp/nonexistent-file.html'" (14ms)
→ {uri: "ftp://example.com"} → "Error: Unsupported URI scheme: ftp. Supported schemes are: file:, data:, http:, https:" (6ms)
→ {uri: "data:text/html;base64,"} → "" (empty string, stderr warning about replacement chars) (14ms)

All errors are graceful text responses (not MCP error codes). Invalid scheme gives explicit supported-scheme list.

⚠️ KEY GOTCHAS

1. Code blocks lose language annotation — <code class="language-python"> becomes ` without python tag
2. JSON is NOT converted — passes through as raw text (no structural transformation to markdown)
3. data: URIs must be base64-encoded with proper MIME type prefix (data:text/html;base64,...)
4. Empty content returns empty string with a stderr warning about replacement characters
5. **`markitdown-mcp[a

Supplementary findings: markitdown-mcp — XML/RSS, complex HTML, edge cases (11 calls, fresh execution)

Additional format coverage and edge cases not in the original verified answer.

Probe A — XML/RSS → Markdown

→ convert_to_markdown({uri: "data:application/xml;base64,..."})
  Input: RSS 2.0 feed with <channel><title>Test Feed</title><item><title>First Post</title><description>Hello world</description></item></channel>
← "# Test Feed\nHello world\n\n## First Post\nHello world"
Latency: 53ms

RSS feeds auto-converted: channel title becomes # H1, items become ## H2 sections. Description text extracted. This format was NOT tested in the original answer.

Probe B — Complex HTML (blockquotes, code, ordered lists, hr, images, details)

→ convert_to_markdown({uri: "data:text/html;base64,..."})
  Input: <h1>Report</h1><blockquote>Important quote</blockquote><pre><code>const x = 42;\nconsole.log(x);</code></pre><hr/><h2>Section 2</h2><ol><li>First</li><li>Second</li></ol><img src="photo.jpg" alt="A photo"/><details><summary>Click to expand</summary><p>Hidden content</p></details>
← "# Report\n\n> Important quote\n\n```\nconst x = 42;\nconsole.log(x);\n```\n\n---\n\n## Section 2\n\n1. First\n2. Second\n3. Third\n\n![A photo](photo.jpg)Click to expand\n\nHidden content"
Latency: 7ms

All elements converted correctly except: <details>/<summary> loses its expandable semantic — summary text is inlined and hidden content appears below without any markdown equivalent. <img> becomes ![alt](src).

Probe C — HTTP URL latency

→ convert_to_markdown({uri: "https://httpbin.org/html"})
← Moby-Dick excerpt rendered as clean markdown
Latency: 34267ms (!!)

⚠️ HTTP URLs can be EXTREMELY slow (~34 seconds for a small page). The original answer showed 289ms for example.com — highly variable based on target site response time and content size.

Probe D — Markdown round-trip

→ convert_to_markdown({uri: "data:text/markdown;base64,..."})
  Input: "# Heading\n\n**Bold** and *italic*\n\n- List item 1\n- List item 2\n"
← Identical output — perfect preservation
Latency: 7ms

Markdown input passes through perfectly — useful for normalizing markdown from unknown sources.

Probe E — Empty HTML

→ convert_to_markdown({uri: "data:text/html;base64,..."})
  Input: <html><body></body></html>
← "" (empty string)
Latency: 8ms

Empty content returns empty string (no error, no crash).

⚠️ ADDITIONAL GOTCHAS (supplement to original)

1. XML/RSS support works — feeds auto-detected and channel/items extracted as headings
2. `<details>/<summary>` semantic lost — content extracted inline, expandable behavior gone
3. HTTP URL latency wildly variable — can be 289ms (example.com) to 34s+ (httpbin.org) depending on target
4. `data:application/xml;base64,...` is the correct MIME type for XML/RSS data URIs
5. Markdown round-trips perfectly — text/markdown MIME type recognized