How to Use MarkItDown MCP Server with Claude Desktop for Document Processing

Mar 22, 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 now read any document format - PDF, DOCX, XLSX, PPTX, HTML - without me doing any manual conversion. This post shows how I set it up.

What is MarkItDown MCP Server?

The markitdown-mcp package provides an MCP (Model Context Protocol) server that exposes document conversion capabilities to Claude. It converts documents to Markdown format, which Claude can then process natively.

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

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

This means Claude can read documents from anywhere without me lifting a finger.

Installation

First, I installed the MCP server package:

pip install markitdown-mcp

For production use, I recommend using Docker instead. I’ll cover that in the Docker section.

Configure Claude Desktop

After installation, I needed to tell Claude Desktop about this MCP server.

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.

Using in Claude Desktop

After setup, I tested it with a simple request:

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

Claude automatically called the convert_to_markdown tool and provided a summary. No manual conversion needed.

Here’s what happened under the hood:

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

I can also use HTTP URLs:

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

Claude handles both local files and remote URLs the same way.

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
SSE	Server-Sent Events for real-time updates

For Claude Desktop, STDIO is the default and requires no extra configuration.

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): Safe, as it only runs locally with your permissions
For HTTP/SSE mode: Bind to localhost only, never expose to the network

# Safe - only accessible locally
markitdown-mcp --transport sse --host 127.0.0.1 --port 8080

# Dangerous - DO NOT expose to network
# markitdown-mcp --transport sse --host 0.0.0.0 --port 8080

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 MarkItDown MCP server bridges Claude Desktop with document processing capabilities. Once configured, Claude can read PDFs, Word documents, Excel files, 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
Add to Claude Desktop config in the mcpServers section
Restart Claude Desktop after configuration changes
Use Docker for better isolation and reproducibility
For HTTP/SSE modes, 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

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