MarkItDown MCP Server: Setup, the Security Tradeoff, and a Hosted Alternative

If you have wired an AI agent up to read your files, you have probably run into MarkItDown MCP — Microsoft's Model Context Protocol server that wraps its open-source markitdown library so Claude, Cursor, and other MCP clients can convert a PDF, DOCX, or PPTX to Markdown mid-conversation instead of you doing it by hand. It is a genuinely useful idea: instead of pasting a document into a prompt and hoping the model transcribes it faithfully, the agent calls a real extraction engine and gets structured Markdown back. This post covers what it actually does, how to install it, a security tradeoff worth knowing before you run it, and a hosted MCP alternative if you would rather skip the local setup — courtesy of file2markdown, which runs one.

What MarkItDown MCP Actually Does

MarkItDown MCP is a thin server layer over Microsoft's markitdown Python package. It exposes a convert_to_markdown tool that your MCP client — Claude Desktop, Claude Code, Cursor, VS Code — can call with a file path or URL, and returns clean Markdown: headings, tables, and lists preserved instead of flattened into a wall of text. Under the hood it handles the same formats as the underlying library: PDF, Word, PowerPoint, Excel, HTML, CSV, JSON, XML, EPUB, images (via OCR), and audio (via transcription).

The appeal is obvious if you have ever asked a model to "just give me the markdown" for a document pasted into a prompt: the model retypes what it sees, and retyping means paraphrasing, invented table cells, and quiet truncation on anything long. A conversion tool call sidesteps that entirely — the agent gets the document's actual text and structure, not the model's memory of it.

Setting It Up

Installation is a single pip command:

pip install markitdown-mcp

By default the server runs over stdio, which is what most desktop MCP clients expect. To wire it into Claude Desktop or a similar client, add it to your MCP config:

{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp"
    }
  }
}

It also supports HTTP and SSE transport if you want to run it as a standalone service rather than a per-client subprocess — useful if multiple tools on one machine need to share a single instance.

The Security Tradeoff You Should Know About

Before you point this at production data, it's worth understanding how it fails. Security researchers at OX Security found that MarkItDown MCP's convert_to_markdown tool accepts file paths and file:// URIs without restricting them to a working directory. In practice, that means a malicious prompt, a compromised MCP client, or a local process that can influence the tool call can ask the server to read arbitrary files on disk — SSH keys, cloud credentials, .env files — and get their contents back as "converted" Markdown, limited only by whatever privileges the server process itself has.

Microsoft's stated position is that this is expected behavior rather than a bug: the server is designed to run locally over stdio with the same access as the user who started it, similar to any other local tool that opens files on your behalf. The practical risk shows up if you run it in HTTP or SSE mode and expose it beyond 127.0.0.1 — at that point an unauthenticated network client can request local file reads. If you do run it that way, the sane mitigation is containerizing it (a mcp/markitdown Docker image exists for this) so a compromised request can't reach anything outside the container, and keeping it bound to localhost otherwise. (Verified against OX Security's published disclosure, checked 2026-09-04.)

None of this makes MarkItDown MCP unsafe to use — plenty of local dev tools have the same "runs with your privileges" model. It just means "MCP server" doesn't imply a sandbox, and a server whose whole job is reading files deserves the same scrutiny as any other file-access tool on your machine.

A Hosted Alternative

If you would rather not install a Python package, manage a local process, or think about container isolation at all, file2markdown runs a hosted MCP server at mcp.file2markdown.ai/mcp that does the same core job — file or URL in, Markdown out — without touching your filesystem beyond the specific file or link you hand it. It exposes:

• convert_url — fetch a public URL (PDF, DOCX, web page, and more) and return Markdown.
• convert_base64 — convert file contents directly, for programmatic clients that already have the bytes.
• list_supported_formats and usage_status — introspection tools for what's supported and how much of your quota is left.

The free tier works with no signup — 5 conversions per day per network, files up to 25MB. A Pro API key removes the daily cap, raises the size limit to 100MB, and adds OCR for scanned PDFs and images (checked against file2markdown's own /mcp and pricing pages, 2026-09-04). Adding it to Claude Code is one line:

claude mcp add --transport http file2markdown https://mcp.file2markdown.ai/mcp

For Cursor or any client that takes a JSON config, add the endpoint the same way you would MarkItDown's:

{
  "mcpServers": {
    "file2markdown": {
      "url": "https://mcp.file2markdown.ai/mcp"
    }
  }
}

MarkItDown MCP vs. file2markdown MCP

	MarkItDown MCP	file2markdown MCP
Setup	pip install, run locally	Hosted, add the URL and go
Runs with	Your local user's file privileges	No local file access — reads only the URL/file you send it
Formats	PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, XML, EPUB, images, audio	PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, XML, EPUB, and more via /convert
OCR	Included	Pro tier only
Maintenance	You patch and run it	Managed

If you already have a Python environment for your agent tooling and are comfortable running things locally, MarkItDown MCP is free and well-documented. If you want one less local process to secure and patch, a hosted server is the lower-friction option — and you can always fall back to the plain document converter for a one-off file instead of setting up either.

For everything else about getting documents AI-ready — not just via MCP — see our guides on converting PDFs to Markdown for LLMs, the PDF-to-Markdown API, and what MarkItDown is if you want the non-MCP, plain-library version.

Frequently Asked Questions

What is MarkItDown MCP?

It's Microsoft's Model Context Protocol server for the open-source markitdown Python library. It lets MCP clients like Claude Desktop, Claude Code, and Cursor call a convert_to_markdown tool mid-conversation instead of you converting files separately and pasting the output.

Is MarkItDown MCP safe to run?

It's safe for its intended use — a local tool running over stdio with your own file privileges. The risk security researchers flagged is specific to exposing it over HTTP/SSE beyond 127.0.0.1, where an unauthenticated caller could request arbitrary local file reads. Keep it bound to localhost or run it in a container if you need network access.

Can I use MarkItDown with Claude Desktop or Cursor?

Yes. Install markitdown-mcp via pip and add it to your client's MCP server config with "command": "markitdown-mcp". Both Claude Desktop and Cursor support this config format.

How is file2markdown's MCP server different from MarkItDown MCP?

The core job is the same — convert a document to Markdown for an agent — but file2markdown's is hosted, so there's nothing to install or patch and it never touches your local filesystem beyond the file or URL you explicitly send it. MarkItDown MCP runs locally with your file-system privileges, which is fine for local-only use but is the thing to be careful with if you expose it over a network.