Skip to main content
Claude Desktop supports the Model Context Protocol, allowing it to use external tools like the MarkItDown MCP server. This guide shows you how to configure Claude Desktop to convert documents to Markdown during conversations.

​
Overview

When integrated with Claude Desktop, the MarkItDown MCP server enables Claude to:
  • Convert documents from URLs or local files to Markdown
  • Analyze document content and answer questions about it
  • Extract information from various file formats
  • Process documents as part of natural conversations
It is recommended to use the Docker image when running the MCP server for Claude Desktop. This provides isolation and includes all necessary dependencies.

​
Prerequisites

  • Claude Desktop installed on your system
  • Docker installed (recommended) or markitdown-mcp via pip
  • For Docker: Build the markitdown-mcp image (see Installation)

​
Configuration File Location

Claude Desktop reads MCP server configurations from a JSON file. The location varies by operating system:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
For detailed instructions on finding this file, see the MCP quickstart guide.

​
Basic Configuration (Docker)

Edit claude_desktop_config.json and add the following configuration: 
{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "markitdown-mcp:latest"
      ]
    }
  }
}
This configuration:
  • Names the server “markitdown” (visible in Claude Desktop)
  • Runs the Docker container in STDIO mode
  • Uses --rm to automatically clean up the container after use
  • Uses -i for interactive mode (required for STDIO)

​
Configuration with Local File Access

To allow Claude to access local files, mount a directory into the container: 
{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/home/user/Documents:/workdir",
        "markitdown-mcp:latest"
      ]
    }
  }
}
Replace /home/user/Documents with the actual path to the directory you want to access. On Windows, use Windows-style paths like C:\\Users\\YourName\\Documents.

​
How It Works

  • Files in /home/user/Documents are mounted to /workdir in the container
  • To reference a file, use the path inside the container: file:///workdir/filename.pdf
  • You can mount multiple directories by adding more -v arguments

​
Example: Multiple Mounts

{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/home/user/Documents:/documents",
        "-v",
        "/home/user/Downloads:/downloads",
        "markitdown-mcp:latest"
      ]
    }
  }
}

​
Configuration with pip Installation

If you installed markitdown-mcp via pip instead of Docker: 
{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp",
      "args": []
    }
  }
}
When using pip installation, ensure markitdown-mcp is in your PATH and accessible from the user running Claude Desktop.

​
With Plugins Enabled

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

​
Enabling Plugins

To enable optional MarkItDown plugins, set the MARKITDOWN_ENABLE_PLUGINS environment variable: 
{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MARKITDOWN_ENABLE_PLUGINS=true",
        "markitdown-mcp:latest"
      ]
    }
  }
}
The Docker image has plugins enabled by default. This configuration is only needed if you want to explicitly control the setting.

​
Applying Configuration Changes

After editing claude_desktop_config.json:
  1. Save the file
  2. Completely quit Claude Desktop (not just close the window)
  3. Restart Claude Desktop
  4. The MarkItDown server should now be available

​
Using MarkItDown in Claude

Once configured, you can ask Claude to convert documents:

​
Example Prompts

Converting from URL:
“Can you convert this PDF to markdown? https://example.com/document.pdf”
Converting local file:
“Please convert /workdir/report.docx to markdown and summarize it”
Analyzing content:
“Convert /workdir/sales.xlsx to markdown and tell me the total revenue”
Claude will automatically:
  1. Detect that it needs to use the convert_to_markdown tool
  2. Call the MCP server with the appropriate URI
  3. Receive the Markdown content
  4. Process and respond based on your request

​
Verifying the Integration

To verify the MCP server is working:
  1. Open Claude Desktop
  2. Look for a 🔌 (plug) icon or “Tools” indicator in the interface
  3. Ask Claude: “What MCP tools do you have access to?”
  4. Claude should mention the convert_to_markdown tool from the markitdown server

​
Troubleshooting

​
Server Not Showing Up

  • Verify the JSON syntax is correct (use a JSON validator)
  • Check that Docker is running (for Docker-based configs)
  • Ensure the image name matches: markitdown-mcp:latest
  • Restart Claude Desktop completely

​
File Access Errors

  • Verify the mount path exists and is readable
  • Check that file paths use the container path (e.g., /workdir/...)
  • Ensure the Docker container has permission to access the mounted directory

​
Permission Issues

  • On Linux/macOS, you may need to adjust the USERID and GROUPID in the Docker build: 
    docker build --build-arg USERID=$(id -u) --build-arg GROUPID=$(id -g) -t markitdown-mcp:latest .

​
Debugging

To debug issues:
  1. Test the server independently using mcpinspector
  2. Check Claude Desktop logs (location varies by OS)
  3. Test the Docker command manually in a terminal
  4. Verify the configuration file has valid JSON syntax

​
Advanced Configuration

​
Custom Image Tag

If you built the image with a different tag: 
{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "my-custom-markitdown:v1.0"
      ]
    }
  }
}

​
Multiple MCP Servers

You can configure multiple MCP servers in the same file: 
{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "markitdown-mcp:latest"]
    },
    "another-server": {
      "command": "other-mcp-server",
      "args": []
    }
  }
}

​
Security Considerations

Be careful when mounting directories. The MCP server will have read access to all files in mounted directories.

​
Best Practices

  1. Mount only necessary directories: Don’t mount your entire home directory
  2. Use read-only mounts when possible: 
    "-v", "/path/to/dir:/workdir:ro"
  3. Avoid mounting sensitive directories: Don’t mount directories containing credentials or private keys
  4. Review file paths: Always verify file paths before asking Claude to process them

​
Next Steps

Usage Guide

Learn more about the MCP server features

Supported Formats

See all document formats supported by MarkItDown

Build docs developers (and LLMs) love

Get started for freeTalk to us