MarkItDown is a free, open-source Python tool from Microsoft that converts files (PDF, Word, Excel, PowerPoint, images, audio, HTML, YouTube URLs) into clean Markdown text. It has over 150,000 GitHub stars and is MIT licensed.

What file formats does MarkItDown support?

MarkItDown supports PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), images (with OCR), audio (with transcription), HTML, CSV, JSON, XML, ZIP files, YouTube URLs, and EPubs.

Do I need Docker to run MarkItDown MCP?

No. The simplest setup uses pip install markitdown-mcp and runs natively on your machine. Docker is an optional alternative for containerized workflows or production environments.

MarkItDown MCP Setup for Claude Desktop

Q: How does MarkItDown reduce token usage?

When you upload a raw PDF to Claude, the file includes formatting metadata, broken tables, embedded images, and layout junk. Each page can consume 1,500 to 3,000 tokens. MarkItDown strips all of that and returns clean Markdown, reducing token usage by up to 70%.

What this SOP covers

Every time you upload a PDF, Word document, or spreadsheet to Claude, the raw file includes formatting metadata, broken tables, embedded images, and layout noise. Each PDF page can consume between 1,500 and 3,000 tokens before you type a single question.

MarkItDown is a free, open-source tool from Microsoft (150,000+ GitHub stars, MIT licensed) that converts files into clean Markdown text. When connected to Claude Desktop as an MCP server, it automatically converts every uploaded file, dropping token usage by up to 70%. Claude was trained on millions of Markdown documents and understands the format natively, so you also get better, more accurate answers.

This SOP walks you through connecting MarkItDown to Claude Desktop using the MCP (Model Context Protocol) approach. After setup, every file you upload is automatically converted. No manual steps needed.

Who this is for

Founders and operators who use Claude Desktop and regularly upload documents for analysis, summarization, or extraction.

Tools needed

Claude Desktop Python 3.10+ Terminal / Command Prompt

Install Python

MarkItDown requires Python 3.10 or higher. If you already have Python installed, skip to Step 2.

Go to python.org/downloads and download the latest version for your operating system
Run the installer. On Windows, tick the checkbox that says Add Python to PATH before clicking Install
Open your terminal (Terminal on Mac, Command Prompt or PowerShell on Windows) and verify the installation:

bash python --version

You should see something like Python 3.12.x. Any version 3.10 or above works.

TIP

On macOS, you may need to use python3 instead of python. If python --version returns an error, try python3 --version instead.

Install the MarkItDown MCP package

The MCP server is distributed as a single pip package. One command installs the server and all file format converters.

bash pip install markitdown-mcp

This installs the markitdown-mcp package, which includes the MarkItDown library with all format converters (PDF, Word, Excel, PowerPoint, images, audio, HTML, and more).

NOTE

On macOS/Linux, you may need to use pip3 instead of pip. If you get a permissions error, add the --user flag: pip install --user markitdown-mcp

Locate the Claude Desktop config file

Claude Desktop reads its MCP server configuration from a JSON file called claude_desktop_config.json. The file location depends on your operating system:

Operating System	File Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

macOS: Open Finder, press Cmd + Shift + G, paste the path above, and press Enter
Windows: Press Win + R, type %APPDATA%\Claude, and press Enter. The folder opens in File Explorer
If the file does not exist yet, create a new file named claude_desktop_config.json in that folder with this content: { }

Add the MarkItDown server entry

Open claude_desktop_config.json in any text editor (Notepad, VS Code, TextEdit) and add the MarkItDown MCP server configuration.

If the file is empty or contains only { }, replace its contents with:

json

{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp",
      "args": []
    }
  }
}

If you already have other MCP servers configured, add the "markitdown" entry inside the existing mcpServers object:

json

{
  "mcpServers": {
    "your-existing-server": {
      "command": "...",
      "args": ["..."]
    },
    "markitdown": {
      "command": "markitdown-mcp",
      "args": []
    }
  }
}

WARNING

The JSON must be valid. A single stray comma or missing quote will prevent Claude Desktop from loading any MCP servers. If you are unsure, paste your config into jsonlint.com to validate it before saving.

IMPORTANT

Windows users: If the markitdown-mcp command is not found after installation, you may need to use the full path to the executable instead. Find it by running where markitdown-mcp in Command Prompt, then use that full path as the "command" value. Remember to escape backslashes in JSON (use \\ instead of \).

Restart Claude Desktop

Claude Desktop only reads MCP server configurations at startup. You must fully quit and reopen the app. Closing the window is not enough.

macOS: Press Cmd + Q to fully quit, then reopen Claude Desktop from your Applications folder or Dock
Windows: Right-click the Claude icon in the system tray (bottom-right of the taskbar) and select Quit. Then reopen the app

TIP

If you just click the red close button on macOS, the app keeps running in the background. Always use Cmd + Q to ensure a full restart.

Verify the connection

After restarting, confirm that Claude Desktop has loaded the MarkItDown MCP server.

Open a new conversation in Claude Desktop
Look for the MCP tools icon (a small hammer icon) near the text input bar at the bottom of the screen
Click it to see the list of available MCP tools
You should see convert_to_markdown listed under the "markitdown" server

If you see the tool listed, the connection is working. Move on to Step 7.

If you do not see it, check the Troubleshooting section below.

Test with a file

Upload any supported file to Claude Desktop and watch the conversion happen automatically.

Start a new conversation in Claude Desktop
Upload a PDF, Word document, Excel spreadsheet, PowerPoint, or any other supported file
Ask Claude a question about the file (for example: "Summarize this document" or "Extract the key points from this PDF")
Claude will automatically call the convert_to_markdown tool, convert the file to clean Markdown, and then respond based on the converted content

TIP

You can also convert remote files by giving Claude a URL. For example: "Read this document at https://example.com/report.pdf and list the key findings." Claude will fetch and convert the file through the MCP server.

Here is the full list of file formats MarkItDown supports:

Format	File Types
Documents	PDF, Word (.docx), PowerPoint (.pptx)
Spreadsheets	Excel (.xlsx, .xls), CSV
Web	HTML, XML, JSON
Media	Images (EXIF + OCR), Audio (transcription)
Other	ZIP (iterates contents), YouTube URLs, EPubs

Frequently Asked Questions

How does MarkItDown reduce token usage?

When you upload a raw PDF, Claude processes the entire file including formatting metadata, embedded fonts, broken table structures, and image data. MarkItDown strips all of that and returns only the structured text as Markdown. The result: the same content uses significantly fewer tokens, and Claude can process longer documents without hitting context limits.

Does this work with Claude Code too?

Yes. The markitdown-mcp package works with both Claude Desktop and Claude Code. The MCP server configuration approach is the same for both environments.

Do I need Docker?

No. The pip install approach in this SOP runs natively on your machine and is the simplest option. Docker is available as an alternative for containerized or production environments, but it is not required for this setup.

Is MarkItDown free?

Yes. MarkItDown is fully open-source under the MIT license. It is maintained by Microsoft's AutoGen team and has over 150,000 stars on GitHub. There are no subscription fees, API costs, or usage limits.

What about scanned PDFs or image-heavy documents?

For basic PDF text extraction, the standard installation works well. For scanned documents or PDFs with embedded images that need OCR, you can install the optional markitdown-ocr plugin, which uses LLM Vision (like GPT-4o) to extract text from images. This requires an OpenAI API key and incurs separate API costs.

Will this work for YouTube videos?

Yes. MarkItDown can extract transcripts from YouTube URLs. Simply give Claude a YouTube link and ask it to summarize or extract content. The MCP server will handle the conversion.

Troubleshooting

MarkItDown does not appear in the MCP tools list

You did not fully quit Claude Desktop. Closing the window does not reload MCP servers. Press Cmd + Q (Mac) or right-click the system tray icon and select Quit (Windows), then reopen the app.

Claude Desktop fails to start or shows an error after editing the config

The JSON in your config file is malformed. Common mistakes: a trailing comma after the last entry, mismatched quotes, or unescaped backslashes in Windows paths. Paste your config into jsonlint.com to find the error.

"markitdown-mcp" command not found

Python's Scripts directory is not in your system PATH. On Windows, run where markitdown-mcp to find the full path, then use that as the "command" value in your config file (remember to escape backslashes with \\). On macOS/Linux, try which markitdown-mcp or reinstall with pip3 install markitdown-mcp.

Conversion works but local files cannot be found

When referencing local files via a file:// URI, use the full absolute path. On macOS: file:///Users/yourname/Documents/report.pdf. On Windows: file:///C:/Users/yourname/Documents/report.pdf. Relative paths will not resolve.

PDF table data comes out scrambled

MarkItDown's PDF converter works best with text-based PDFs. Complex table layouts, scanned documents, and heavily formatted PDFs may not convert perfectly. For high-fidelity PDF extraction, consider using the markitdown-ocr plugin or Microsoft's Azure Document Intelligence integration.

MarkItDown GitHub Repository
github.com/microsoft/markitdown