MarkItDown Python and MCP Experiment Log: 14 Fixtures and a Raw STDIO Handshake

This log records the environment, commands, fixture results, and MCP handshake behind the Python guide and MCP setup guide. It reports one run from 2026-09-23; anything not tested is marked explicitly.

Run record

Field	Value
Post IDs	python-guide / mcp-guide
Run date	2026-09-23
Operator	Commands executed with AI assistance; outputs recorded as returned (manual review pending)
Environment	macOS (Darwin 26.5.1, Apple Silicon), uv 0.10.8, Python 3.12 (uv venv --python=3.12)
Tools	markitdown 0.1.8 (released on PyPI 2026-09-21), markitdown-mcp 0.0.1a7 (released on PyPI 2026-09-14)
Conversion mode	Local CLI markitdown <file> (no LLM client, plugins, or Azure services); MCP over STDIO
Inputs	14 public fixtures from samples/quality-gallery/files/
Output path	Temporary directory, not committed; key results are excerpted here and in the companion guides
Status	run; manual review is pending

The following installation commands were run:

uv venv --python=3.12 mdvenv
uv pip install --python mdvenv/bin/python 'markitdown[all]' markitdown-mcp  # initially resolved markitdown to 0.1.5
uv pip install --python mdvenv/bin/python --prerelease=allow 'markitdown[all]==0.1.8'  # upgraded to 0.1.8

One installation wrinkle: in this environment, the Azure-related extra for markitdown[all] 0.1.8 depended on a prerelease package. Without prereleases enabled, the resolver fell back to markitdown 0.1.5 without an error. Installing only the needed extras (for example, markitdown[pdf,docx,xlsx,pptx]) or enabling prereleases avoids that resolution path.

Conversion results (markitdown 0.1.8)

Input	Exit	Lines	Chars	Table rows	Observation
release-overview.pdf	0	46	1255	0	Headings and paragraphs retained
q3-results.pdf	0	23	1453	13	Pipeline table retained; numeric values matched, with blank spacer columns between value columns
library-note.pdf	0	34	2556	14	Two tables; usable
customer-research-brief.docx	0	22	581	6	Headings and lists intact; a table header cell was empty
q3-budget.xlsx	0	18	582	15	Sheet names became ## headings; an Unnamed: 1 header artifact appeared
workshop-budget.pptx	0	7	189	0	Text only; layout was not retained
ab-test-note.html	0	29	1386	0	Clean output
urban-orchards.epub	0	28	692	5	Chapters became headings
churn-cohort-notebook.ipynb	0	24	453	0	Cell source was concatenated
moving-averages-scan.pdf	0	1	1	0	No text layer; output was one newline despite exit code 0 (silent failure)
q3-results-scan.pdf	0	1	1	0	Same: one newline despite exit code 0
delivery-note-scan.pdf	0	1	1	0	Same: one newline despite exit code 0
workshop-budget-scan.png	0	2	22	0	Only ImageSize: 1600x1100 metadata
delivery-note-scan.png	0	2	21	0	Metadata only

For these fixtures, headings, lists, and simple tables were usable, though some tables had artifacts. Three scanned PDFs returned a single newline with exit code 0, so a successful process exit did not guarantee useful output; check output length. This run did not test LLM image descriptions, the markitdown-ocr plugin, or Azure Document Intelligence / Content Understanding because credentials were unavailable. Any mention of those capabilities elsewhere is based on the official README, not on this run.

MCP handshake (markitdown-mcp 0.0.1a7 over STDIO)

The test wrote JSON-RPC messages to the markitdown-mcp process in this order: initialize → notifications/initialized → tools/list → tools/call, then read stdout.

• initialize returned serverInfo = {"name":"markitdown","version":""} and protocol version 2025-06-18.
• tools/list returned one tool, convert_to_markdown, with one required string parameter: uri.
• tools/call with file:///…/q3-results.pdf returned isError: false and text content containing the converted Markdown. Its first lines matched the CLI output.
• The package requirements recorded for this run were markitdown[all]>=0.1.1,<0.2.0 and mcp>=2.1.1,<3.0.0.

Claude Desktop, Cursor, and Cline GUI configurations were not tested because those clients were not available in the environment. Their examples came from the official README and client documentation. The Docker image was not built or verified.

AI disclosure: This article was translated and prepared with AI from the experiment record captured on 2026-09-23. The experiment is reported as run; manual review has not been completed. Claude Desktop, Cursor, and Cline GUI setup and the Docker image build were not tested.