MarkItDown

The MarkItDown MCP server connects your AI assistants directly to Microsoft’s MarkItDown Python utility.

It enables you to convert a whole bunch of different file types into clean, structured Markdown, specifically for Large Language Models (LLMs) and text analysis pipelines.

Features

• 📄 Full File Support: Converts PDF, PowerPoint, Word, Excel, HTML, and even text-based formats like CSV, JSON, and XML.
• 🖼️ Multimedia Conversion: Extracts EXIF metadata and performs OCR on images; it also handles speech transcription for audio files.
• 🗂️ Archive Handling: Intelligently iterates over the contents of ZIP files to convert each file within.
• 🌐 Flexible URI Scheme: Accepts http:, https:, file:, or data: URIs as input for conversion.
• 💻 Multiple Server Modes: Runs as a standard STDIO service or as a Streamable HTTP and Server-Sent Events (SSE) server for web-based integrations.

Use Cases

• Building a RAG Pipeline: If you’re creating a Retrieval-Augmented Generation system, you need to feed it a knowledge base. You can use this server to convert a directory full of PDFs, Word documents, and PowerPoints into clean Markdown. This standardized format makes it much easier to chunk the documents and load them into a vector database for the LLM to query.
• Local File Access for AI Assistants: AI models like Claude Desktop can’t directly access your local file system. By running the MarkItDown-MCP server (especially the Docker version), you can create a secure bridge. This lets the model “read” local files by calling the conversion tool, perfect for summarizing a report you just downloaded or analyzing a local spreadsheet.
• Automating Content Workflows: Imagine you have a workflow where user-uploaded files need to be processed. You can set up the HTTP server to receive a file URI, convert it to Markdown, and then pass the text to another service for summarization, translation, or analysis. This automates the entire content ingestion process.
• Enhancing Developer Tools: You can integrate the server with code editors and other developer tools. For instance, a custom command in your editor could point to a file, convert it to Markdown on the fly, and display it in a preview pane, which is great for quickly inspecting document contents without leaving your development environment.

How To Use It

1. Install the package using pip:

pip install markitdown-mcp

2. You have a couple of options for running the server. For simple, local command-line interactions, the default STDIO mode is sufficient:

markitdown-mcp

If you need to connect to it from a web application or another service over the network, you can run it in HTTP mode:

markitdown-mcp --http --host 127.0.0.1 --port 3001

3. For a more isolated and portable setup, especially when connecting to Claude Desktop, using Docker is the recommended path.

Build the image from the Dockerfile:

docker build -t markitdown-mcp:latest .

Run the container. This command is fine for converting remote web content:

docker run -it --rm markitdown-mcp:latest

To let the server access your local files, you must mount a volume. For example, to make files in /home/user/data available inside the container:

docker run -it --rm -v /home/user/data:/workdir markitdown-mcp:latest

Files in your local /home/user/data directory will now be accessible at /workdir/ inside the container.

4. To hook the server into Claude Desktop, you need to edit its configuration file. You can find the claude_desktop_config.json file in the application support directory for your operating system.

Add this entry to the mcpServers object to run the Docker container as the server:

{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "markitdown-mcp:latest"
      ]
    }
  }
}

If you need to mount a local directory, modify the args to include the volume flag:

{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
   "run",
   "--rm",
   "-i",
   "-v",
   "/home/user/data:/workdir",
   "markitdown-mcp:latest"
      ]
    }
  }
}

5. If you run into issues, the mcpinspector tool is your best friend for debugging.

Install and run it with npx:

npx @modelcontextprotocol/inspector

This will launch a web interface at http://localhost:5173/. From there, you can connect to your running markitdown-mcp server regardless of the mode (STDIO, HTTP, or SSE) and test the convert_to_markdown tool directly.

FAQs

Q: What’s the main difference between the STDIO and HTTP/SSE modes?
A: STDIO (Standard Input/Output) is for command-line or local script interaction, where the server communicates directly through the terminal’s input and output streams. Streamable HTTP and SSE (Server-Sent Events) modes run a web server, which is better for integrations with web apps, remote services, or any scenario where you need to communicate over a network.

Q: Can I convert a local file if I’m running the server in Docker?
A: Yes, but you have to explicitly grant the Docker container access to your local files. You do this by mounting a local directory as a volume using the -v flag when you run the docker run command. Without this, the container is isolated from your host machine’s filesystem.

Q: Is it secure to expose the HTTP server to the internet?
A: The server does not have built-in authentication. For security, you should only run it bound to localhost (which is the default) and avoid exposing it directly to the public internet. If you need remote access, it’s better to put it behind a reverse proxy that handles authentication and SSL.

Q: Will the Markdown output look exactly like my original document?
A: The goal is to preserve the structure and content, not to create a perfect visual replica. Headings, lists, tables, and text will be correctly formatted in Markdown, but the output is optimized for text analysis by LLMs, not for high-fidelity human reading.