Testing the MarkItDown MCP Server End to End: STDIO, One Tool, Four Real Calls
Disclosure: I maintain markitdown.tech. It is built on Microsoft's open-source MarkItDown library, but it is not affiliated with Microsoft. The markitdown-mcp server tested here is Microsoft's own open-source package. I
Disclosure: I maintain markitdown.tech. It is built on Microsoft's open-source MarkItDown library, but it is not affiliated with Microsoft. The markitdown-mcp server tested here is Microsoft's own open-source package.
If you want an AI client to read your documents, at some point you have to turn PDFs, spreadsheets and web pages into text it can use. markitdown-mcp puts Microsoft's MarkItDown converter behind the Model Context Protocol, so any MCP host can find a converter and call it, and you don't have to write a parser for each app.
Before wiring it into Claude Desktop or an agent, I wanted to see what the server actually exposes and how it behaves when a call fails. So I installed it in a clean virtual environment and drove it from a small Python MCP client over STDIO, all on one machine. Every terminal screenshot below is real output from that run. Where I did not test something (Docker, Claude Desktop, MCP Inspector), I say so.
For background on where an MCP layer fits and when it is worth adding, see the MarkItDown MCP guide on markitdown.tech.
Step 1: Install the package
In a fresh Python 3.13 venv:
python3 -m venv venv
source venv/bin/activate
pip install markitdown-mcp
That one command pulled in 73 packages, including markitdown 0.1.9 and the mcp SDK 2.3.0. The server itself was markitdown-mcp 0.0.1a8. I did not need a separate pip install 'markitdown[all]', because XLSX and HTML conversion worked with the default dependencies. The --help output shows the whole CLI: STDIO by default, --http for Streamable HTTP plus SSE, and a host that defaults to 127.0.0.1. --sse is now listed as a deprecated alias for --http.
Step 2: Connect a client over STDIO and list the tools
STDIO is the default transport. The client starts markitdown-mcp as a subprocess and talks to it over stdin and stdout, so no network port is opened. Here is the client I used, trimmed to the essentials. I ran this exact script with mcp 2.3.0. Older 1.x SDKs use camelCase attribute names such as isError.
import asyncio, base64, pathlib
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
server = StdioServerParameters(command="markitdown-mcp", args=[])
async def main():
async with stdio_client(server) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
for tool in tools.tools:
print("tool:", tool.name, "-", tool.description)
uris = [
pathlib.Path("samples/book-club.xlsx").resolve().as_uri(),
"data:text/csv;base64,"
+ base64.b64encode(b"city,trip_days\nLisbon,4\nKyoto,6\n").decode(),
]
for uri in uris:
result = await session.call_tool("convert_to_markdown", {"uri": uri})
print("\nisError:", result.is_error)
print(result.content[0].text)
asyncio.run(main())
The server reports itself as markitdown and exposes exactly one tool, convert_to_markdown. Its only input is a required string, uri:
That narrow surface is the main design choice. The client doesn't pick a converter or pass format options. It hands over a URI, and MarkItDown works out the format.
Step 3: Convert local files with file: URIs
For test inputs I made two small files myself: a one-sheet XLSX book-club reading list and a short HTML page of meeting notes with a heading, bold and italic text, a bullet list and a link. I built file:// URIs with pathlib.Path(...).resolve().as_uri() and called the tool once for each file:
What came back:
-
XLSX: the sheet name became a
## Reading listheading, followed by a clean pipe table. The numbers stayed as plain values, such as304. -
HTML:
<h1>became#,<strong>and<em>became**…**and*…*, the list items became*bullets, and the link stayed clickable as[reading list](https://example.com/list). The<title>tag was not repeated in the body.
Step 4: Send inline content with a data: URI and check the error path
data: URIs let a client send content inline, which helps when the bytes are already in memory or the server can't see the client's filesystem. A base64 CSV of two rows came back as a Markdown table.
Then I asked for a file that doesn't exist. The call did not crash the session. It came back with isError: True and a short message, "Could not read the resource: No such file or directory." The server also logged the failure to stderr. Notice that the message does not include the full path that failed, so a client can show it to users without leaking directory names.
Bonus: Streamable HTTP, bound to localhost only
I also started the HTTP transport, bound only to the loopback address:
markitdown-mcp --http --host 127.0.0.1 --port 3001
ss showed it listening on 127.0.0.1:3001 only. A Python client using streamable_http_client("http://127.0.0.1:3001/mcp") listed the same single tool and converted a small data:text/html URI into ## Hello over HTTP. I stopped the server right after the test.
The security note you should not skip
The README warns about this plainly: the server does not support authentication, and it runs with the privileges of the user who starts it. convert_to_markdown can read any file that user can read, and it can fetch data from the network. That is why HTTP and SSE mode bind to localhost by default. Even on localhost, other processes and users on the same machine can reach it. The README suggests a VM or container if you need stronger isolation. Keep it on 127.0.0.1 unless you fully understand the risks.
Connecting Claude Desktop (from the docs, not tested here)
I did not test this part: there was no Docker or Claude Desktop on my test machine. The README recommends the Docker image for Claude Desktop. You build the image yourself from the repository's Dockerfile (docker build -t markitdown-mcp:latest .). Then you add this to claude_desktop_config.json:
{
"mcpServers": {
"markitdown": {
"command": "docker",
"args": ["run", "--rm", "-i", "markitdown-mcp:latest"]
}
}
}
To let it read local files, the README mounts a directory into the container, for example "-v", "/home/user/data:/workdir" placed before the image name. Files then show up under /workdir/... inside the container, so your file: URIs need to use the container path, not your host path.
For debugging, the README points to MCP Inspector (npx @modelcontextprotocol/inspector). Choose STDIO with the command markitdown-mcp, or Streamable HTTP at http://127.0.0.1:3001/mcp, then open Tools → List Tools → convert_to_markdown. I did not run the Inspector for this post.
What I'd check before adopting it
The markitdown.tech guide suggests a five-step path: prepare the command, register the client, test tool calls, index the output, and add guardrails. My quick test covered the first and third steps. Before using it in production, I would also try a real PDF, a messy spreadsheet and one awkward file. I would add file-size limits, timeouts and request logging, and I would check that the Markdown chunks well in your retrieval pipeline.
If you mostly want to grab a page you're reading rather than wire up an agent, the earlier post in this series covers the browser side: Save the Page You're Reading as Markdown: A Walkthrough of the Webpage to Markdown Chrome Extension.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.


