How to Install and Use MarkItDown MCP with Claude Desktop

Mar 22, 2026 - Last update: Aug 20, 2026

Purpose

I wanted Claude Desktop to read my documents directly. Every time I had a PDF or Word document to analyze, I had to manually convert it to text first. This broke my workflow and wasted time. Then I discovered the MarkItDown MCP server. With it configured, Claude can read PDF, DOCX, XLSX, PPTX, and other formats without manual conversion. This post shows how to install, connect, and use the Microsoft MarkItDown MCP server with Claude Desktop.

What is MarkItDown MCP Server?

The markitdown-mcp package provides an MCP (Model Context Protocol) server that exposes document conversion capabilities to any MCP client. It is part of Microsoft MarkItDown and converts documents to Markdown format, which clients can then process natively. Claude Desktop is one MCP client among many — this post shows how to use it with Claude Desktop, but the server itself is a general-purpose component, not specific to Claude Desktop.

The server exposes one tool: convert_to_markdown(uri). The URI can be:

file: - Local files
http: or https: - Remote URLs
data: - Data URIs

In practice, this means Claude can read PDF, DOCX, XLSX, PPTX, and other formats without manual conversion, as long as the MarkItDown MCP server has access to the file or URL.

How to Install MarkItDown in Claude Desktop

Here is the quickest way to install Microsoft MarkItDown MCP and start using it with Claude Desktop:

1. Install the package:

pip install markitdown-mcp

2. Add the server to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

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

3. Restart Claude Desktop completely (quit and reopen, not just close the window). The MCP server loads on startup.

4. Test it with a PDF:

User: Please read this PDF file:///Users/me/document.pdf and summarize it.

Claude can call the convert_to_markdown tool when it needs to process the document, returning a summary — no manual conversion needed. For the full configuration details, Docker setup, and more examples, continue reading.

How to Connect MarkItDown to Claude Desktop

After installing MarkItDown MCP, you need to connect it to Claude Desktop by registering the server in the config file.

Step 1: Locate the Config File

The configuration file location depends on the operating system:

Platform	Config Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

On macOS, I opened the config file:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

If the file doesn’t exist, create it with an empty JSON object first.

Step 2: Add MCP Server Configuration

I added the MarkItDown server to the mcpServers section:

Using local installation:

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

If you have other MCP servers, merge this into your existing configuration.

Using Docker (recommended):

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

Step 3: Restart Claude Desktop

I restarted Claude Desktop completely (quit and reopen, not just close window). The MCP server loads on startup. If the tool doesn’t appear, see the Debugging section below.

How to Use MarkItDown in Claude

Once MarkItDown MCP is connected, you don’t need special prompts — just ask Claude to read a document, and it can call the convert_to_markdown tool exposed by the server when processing requires it.

For example, with a PDF:

User: Please read this PDF file:///Users/me/document.pdf and summarize it.

Claude can call the convert_to_markdown tool when it needs to process the document, then provide a summary. Here’s what happens under the hood:

Claude calls: convert_to_markdown("file:///Users/me/document.pdf")
MarkItDown MCP Server: Converts PDF to Markdown text
Claude: Receives the text and processes it

The same flow works for the other formats MarkItDown supports, including DOCX, PPTX, and XLSX:

User: Summarize this Word document file:///Users/me/report.docx
User: Extract the key points from file:///Users/me/deck.pptx
User: Read the data from file:///Users/me/spreadsheet.xlsx

You can also use HTTP URLs — Claude handles local files and remote URLs the same way:

User: Read the document at https://example.com/report.docx and extract key points.

Docker Setup (Recommended)

Docker provides better isolation and reproducibility. Here’s how I set it up:

# Clone the repository
git clone https://github.com/microsoft/markitdown.git
cd markitdown

# Build the Docker image
docker build -t markitdown-mcp:latest -f packages/markitdown-mcp/Dockerfile .

To run the container manually for testing:

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

For local file access, mount a volume:

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

Then in Claude Desktop config, reference files with the mounted path:

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

Transport Options

The MarkItDown MCP server supports three transport modes:

Transport	Use Case
STDIO	Default, for Claude Desktop integration
Streamable HTTP	Remote/HTTP access (preferred for new HTTP setups)
SSE	Legacy/compatible HTTP endpoint, kept for existing clients

For Claude Desktop, STDIO is the default and requires no extra configuration. For HTTP access, prefer the Streamable HTTP transport (--http); SSE remains available as a compatible/legacy endpoint for older clients.

Security Considerations

The README notes an important security point: “The server does not support authentication, and runs with the privileges of the user running it.”

This means:

For STDIO mode (Claude Desktop): STDIO does not directly expose a network port — the server communicates with the client over the process’s standard input and output. However, the MCP server still runs with the privileges of the current user, so it can access any local files and network resources that user has permission to reach.
For HTTP mode: Bind to localhost only, never expose to the network. Use the Streamable HTTP transport (--http) for new setups, and still bind it to localhost unless you have a specific reason not to.

# Current recommended form - only accessible locally
markitdown-mcp --http --host 127.0.0.1 --port 3001

# Dangerous - DO NOT expose to network
# markitdown-mcp --http --host 0.0.0.0 --port 3001

Debugging

When the MCP server doesn’t load properly, I use the MCP Inspector:

npx @modelcontextprotocol/inspector

In the inspector interface:

Select STDIO transport
Enter markitdown-mcp as the command
Click Connect

The inspector shows all available tools and lets me test them directly. This helped me catch a configuration typo once.

Common Issues

Issue 1: Claude Can’t See the Tool

After configuration, Claude didn’t recognize the tool. I checked:

Is the config file valid JSON? (I had a trailing comma)
Did I restart Claude Desktop completely?
Is markitdown-mcp in PATH? (Test with which markitdown-mcp)

Issue 2: File Not Found

When using Docker with local files, Claude couldn’t find the file. The fix was ensuring the volume mount matched:

Local path: /Users/me/documents/report.pdf
Mount: -v /Users/me/documents:/workdir
Claude should use: file:///workdir/report.pdf

Issue 3: Docker Permission Denied

On Linux, I got permission errors with Docker. The fix:

# Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in

Summary

The Microsoft MarkItDown MCP server bridges Claude Desktop with document processing capabilities. Once configured, Claude can read PDFs, Word documents, Excel spreadsheets, and more without manual intervention. The setup takes just a few minutes, and the productivity gain is immediate.

Key points:

Install with pip install markitdown-mcp or use Docker
Connect it to Claude Desktop in the mcpServers section of the config file
Restart Claude Desktop after configuration changes
Use Docker for better isolation and reproducibility
For HTTP mode, bind to localhost only for security

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 MarkItDown GitHub Repository
👨‍💻 Model Context Protocol Documentation
👨‍💻 How to Use MarkItDown: CLI and Python API Guide for Document Conversion

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!