markitdown_mcp_server

MarkItDown MCP Server exposes a conversion service that turns a variety of file formats into Markdown using the MarkItDown utility. Once the server is running, MCP clients can issue the /md command (or equivalent MCP actions) to request a transformation of an input file into Markdown. The server is designed to handle formats such as PDF, PowerPoint, Word, Excel, images (with EXIF metadata and OCR), audio (EXIF metadata and speech transcription), HTML, text-based formats (CSV, JSON, XML), and ZIP files (which are iterated over to extract content). To use it, connect via MCP to the server name defined in your MCP settings (here markitdown_mcp) and invoke the /md command with the path to the input file. The server will process the input and return a Markdown representation suitable for downstream editing or rendering in your MCP client. The README examples show how to configure a client (e.g., Zed Editor) to invoke the server and how to issue the /md command directly for quick conversions.

Prerequisites:

• Python 3.x and a working Python environment
• MCP runtime (uv) installed on your system
• Optional: Smithery CLI if you plan to install via Smithery

Install via Smithery (recommended if you want to install automatically):

1. Ensure you have Node.js and npm installed.
2. Install the Smithery CLI and install the MarkItDown MCP Server:

npx -y @smithery/cli install @KorigamiK/markitdown_mcp_server --client claude

Manual installation (from source):

1. Clone this repository
2. Install dependencies (Python environment required):

uv install

3. Run the MCP server using the MCP runtime (example shown in usage):

uv run markitdown-mcp

4. Connect a client to the server using the MCP protocol and issue the /md command with your input file.

Notes:

• The exact runtime command may differ if you customize paths or deployment targets. Adjust the command and arguments accordingly.
• If you deploy in a container or cloud environment, ensure the input/output paths and any required environment variables are appropriately mapped.

Tips and common issues:

• Ensure the input file size does not exceed any configured limits of your MCP runtime or container, as large documents may take longer to process.
• When processing image or audio files, verify that EXIF data or transcriptions are enabled in the MarkItDown configuration if you need metadata-rich Markdown.
• If you see connection errors, confirm the MCP client is configured to target the exact server name (markitdown_mcp) and that the runtime is listening on the expected host/port.
• Environment variables: you may need to set PATH enhancements so that the uv runtime and MarkItDown dependencies are discoverable. Common vars include PATH and any MO/DL paths needed by MarkItDown.
• If integrating with CMS or editors, you can customize the MCP command mapping (for example, changing /md to a different trigger) in your client settings or MCP gateway.