markitdown

MarkItDown MCP Server is a Python-based MCP server that converts a wide range of file formats into clean, structured Markdown using the MarkItDown library. It exposes MCP tools such as convert_file to process a single file, convert_directory to process all supported files in a directory, and list_supported_formats to query the formats it can handle. You can run the server directly (via the markitdown-mcp executable) or via a Python entry point (e.g., python run_server.py) depending on your setup. In Claude Desktop and other MCP clients, you typically configure the MCP server by specifying the command markitdown-mcp and an empty args array, allowing the client to communicate with the MCP server through the MCP protocol.

To use the tools, connect to the server from your MCP client and invoke the available commands. For example, convert_file accepts a file_path to translate a document into Markdown, list_supported_formats returns the supported file types, and convert_directory processes all compatible files within a given input directory and writes Markdown outputs while preserving the directory structure. The server also supports environment variable configuration via a .env file for deployment-time customization.

Prerequisites:

• Python 3.10 or newer
• Git
• Optional: pipx for easier tool installation

Option A: Install with pipx (recommended)

1. Install the MCP server:

pipx install git+https://github.com/trsdn/markitdown-mcp.git

2. Install all dependencies for full functionality:

pipx inject markitdown-mcp 'markitdown[all]' openpyxl xlrd pandas pymupdf pdfplumber

Option B: Direct usage / development install

1. Clone the repository and install in editable mode:

git clone https://github.com/trsdn/markitdown-mcp.git
cd markitdown-mcp
pip install -e .

2. If you want all features, install extra dependencies similarly:

pip install -e .[all]

Option C: Quick verification

1. Start the MCP server:

markitdown-mcp --help

Or, if you’re running from source:

python run_server.py --help

Tips and common considerations:

• This MCP server relies on MarkItDown and many optional dependencies to support the widest range of formats (PDFs, Excel, images, audio, etc.). If you encounter MissingDependencyException errors, install the Complete Install dependencies as shown in the installation instructions.
• You can inject additional dependencies for specific formats using your MCP client or via pipx/pip installations, for example openpyxl xlrd pandas for Excel support, pymupdf and pdfplumber for PDF processing, and pydub/speechrecognition for audio transcription.
• Environment variables can influence behavior via a .env file. The server supports environment variable configuration to customize paths, API keys, or tool toggles as needed.
• Claude Desktop users should add the MCP server entry with command markitdown-mcp and an empty args array, as shown in the Quick Start, to integrate smoothly with Claude workflows.
• If you see UnicodeDecodeError with some Markdown outputs, it is a known limitation of the MarkItDown workflow; consider adjusting your environment or output encoding as needed.
• The server preserves directory structure in outputs and supports batch processing of entire directories with convert_directory.