MarkItDown (NPX Wrapper) MCP server for AI agents

MarkItDown MCP is a server that converts various file types to markdown, making them accessible to AI assistants that implement the Model Context Protocol (MCP). This NPX wrapper lets you run the MarkItDown MCP server without Docker, handling all Python dependencies automatically.

Installation

Prerequisites

Node.js 16+: Required for NPX execution
Python 3.10+: Required for MarkItDown functionality
Internet Connection: For initial package installation

Optional Dependencies

FFmpeg: For audio file processing and transcription (.mp3, .wav files)
ExifTool: For advanced image metadata extraction

Quick Start

The simplest way to run the server is with NPX:

# Basic STDIO mode (for Claude Desktop)
npx -y markitdown-mcp-npx

# HTTP mode for testing
npx -y markitdown-mcp-npx --http --host 127.0.0.1 --port 3001

# Show help
npx -y markitdown-mcp-npx --help

Alternative Installation Methods

If you prefer a permanent installation:

# Install globally
npm install -g markitdown-mcp-npx

# Then run directly
markitdown-mcp-npx

Usage

Claude Desktop Configuration

To set up the MCP server with Claude Desktop:

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

For HTTP transport:

{
  "mcpServers": {
    "markitdown": {
      "command": "npx",
      "args": [
        "-y",
        "markitdown-mcp-npx",
        "--http",
        "--host",
        "127.0.0.1",
        "--port",
        "3001"
      ]
    }
  }
}

If you installed globally:

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

Command-Line Options

Usage: markitdown-mcp-npx [options]

Options:
  --http           Run with Streamable HTTP and SSE transport (default: STDIO)
  --sse            Alias for --http (deprecated)
  --host HOST      Host to bind to (default: 127.0.0.1)
  --port PORT      Port to listen on (default: 3001)
  --help           Show help message

Usage Examples

Basic STDIO mode (default):

npx -y markitdown-mcp-npx

HTTP/SSE mode:

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

With custom host/port:

npx -y markitdown-mcp-npx --http --host 0.0.0.0 --port 8080

Testing with MCP Inspector

You can test the server using the MCP Inspector:

# Start the inspector
npx @modelcontextprotocol/inspector

# For STDIO mode:
# - Transport: STDIO
# - Command: npx
# - Args: -y, markitdown-mcp-npx

# For HTTP mode:
# - Start server: npx -y markitdown-mcp-npx --http
# - Transport: Streamable HTTP
# - URL: http://127.0.0.1:3001/mcp

Expected Behavior

MarkItDown MCP provides exactly 1 tool called convert_to_markdown that handles all file types:

Documents: PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx)
Images: JPG, PNG, GIF, etc. (with OCR support)
Audio: MP3, WAV (with transcription if FFmpeg installed)
Web: HTTP/HTTPS URLs
Archives: ZIP files
Data: CSV, JSON, XML

Troubleshooting

Server Hangs on Startup

Solution: Ensure you're using the -y flag: npx -y markitdown-mcp-npx

Python Not Found

Solution: Install Python 3.10+ and ensure it's in your PATH

Permission Errors

Solution: Check write permissions to your temp directory

Port Already in Use

Solution: Use a different port with --port <number>

FFmpeg Warning

RuntimeWarning: Couldn't find ffmpeg or avconv - defaulting to ffmpeg, but may not work

This warning is harmless! It means:

✅ MarkItDown is working correctly
✅ All file types work (PDF, Word, Excel, images)
⚠️ Audio files (.mp3, .wav) processing will be limited

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "markitdown" '{"command":"npx","args":["-y","markitdown-mcp-npx"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect