MarkItDown MCP server
Commit Nov 14, 2026Converts over 29 file formats including PDFs, Office documents, images, and audio into structured Markdown for AI workflows.
Also known as trsdn/markitdown-mcp
- Stars
- 48
- Tools
- โ
- Downloads, 30 days
- โ
- Latest version
- โ
- Last commit
- Nov 14, 2026
- License
- MIT
What is MarkItDown MCP?
MarkItDown converts over 29 file formats including PDFs, Office documents, images, and audio into structured Markdown for AI workflows.
Summary generated from the project's README
About MarkItDown MCP server
Converting diverse file formats into structured Markdown for AI workflows is the primary function of this server. It allows developers to transform over 29 different file types, including PDFs, Office documents, images, audio, and archives, into clean text that LLMs can easily process. By using Microsoft's MarkItDown library as a core dependency, it provides high-quality extraction of document structures, tables, and even speech-to-text transcription for audio files.
Users can run this server locally via Claude Desktop or other MCP clients by configuring the command to use markitdown-mcp or uvx. The server provides specific tools such as convert_file for individual documents, convert_directory for batch processing entire folders while preserving directory structures, and list_supported_formats to check compatibility. For full functionality including OCR and audio transcription, users must install additional dependencies like markitdown[all], openpyxl, and pymupdf.
What you can do with it
- 1Convert single documentsTransform a specific PDF or Word document into Markdown text for analysis.
- 2Batch process directoriesConvert every supported file within a folder into Markdown format at once.
- 3Extract image metadataRetrieve EXIF metadata and text content from image files like JPG or PNG.
- 4Transcribe audio filesTurn MP3 or WAV audio recordings into written text using speech recognition.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report โNot verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work ยท What to fix for more points
- Source repository linked and reachabletrsdn/markitdown-mcp is public and reachablegithub.com/trsdn/markitdown-mcp โPass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html โPass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/trsdn/markitdown-mcp โPass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub๐ MarkItDown MCP Server
A powerful Model Context Protocol (MCP) server that converts 29+ file formats to clean, structured Markdown using Microsoft's MarkItDown library.
[!IMPORTANT] This is not Microsoft's official
markitdown-mcppackage. This is an independent community project published on PyPI astrsdn-markitdown-mcp. It uses Microsoft'smarkitdownlibrary as a dependency, but it is developed and maintained separately frommarkitdown-mcpby Microsoft.
- PyPI distribution name:
trsdn-markitdown-mcp- Python import name:
markitdown_mcp- CLI command:
markitdown-mcp(alias:trsdn-markitdown-mcp)
๐ฅ Perfect for Claude Desktop, MCP clients, and AI workflows!
โจ Features
- ๐ MCP Protocol: Seamless integration with Claude Desktop and MCP clients
- ๐ 29+ File Formats: PDFs, Office docs, images, audio, archives, and more
- ๐ Image Metadata: Extract EXIF metadata from images (JPG, PNG, GIF, etc.)
- ๐ต Speech Recognition: Convert audio to text with speech transcription (MP3, WAV)*
*Requires markitdown[all] installation for full functionality
๐ฆ Dependency Requirements by File Type
| File Type | Required Dependencies | Install Command |
|---|---|---|
pypdf, pymupdf, pdfplumber |
pipx inject trsdn-markitdown-mcp 'markitdown[all]' |
|
| Excel (.xlsx, .xls) | openpyxl, xlrd, pandas |
pipx inject trsdn-markitdown-mcp openpyxl xlrd pandas |
| PowerPoint (.pptx) | python-pptx |
Included in base install |
| Images | PIL, exiftool (optional) |
Included in base install |
| Audio | pydub, speech_recognition |
pipx inject trsdn-markitdown-mcp 'markitdown[all]' |
| Basic formats | None | Base install only |
Note: For the best experience, we recommend installing all dependencies using the Complete Install method below.
- ๐ Office Documents: Word, PowerPoint, Excel files
- ๐ Web Content: HTML, XML, JSON, CSV
- ๐ E-books & Archives: EPUB, ZIP files
- โก Fast & Reliable: Built on Microsoft's MarkItDown library
๐ Quick Start for Claude Desktop
-
Install the server with ALL features:
# One command to install everything pipx install trsdn-markitdown-mcp && \ pipx inject trsdn-markitdown-mcp 'markitdown[all]' openpyxl xlrd pandas pymupdf pdfplumber -
Add to your Claude Desktop config:
{ "mcpServers": { "markitdown": { "command": "markitdown-mcp", "args": [] } } } -
Restart Claude Desktop and start converting files!
Features
- Convert multiple file formats to Markdown
- Batch processing of entire directories
- Preserves directory structure in output
- Environment variable support via .env file
๐ Available MCP Tools
๐ง convert_file
Convert a single file to Markdown.
{
"name": "convert_file",
"arguments": {
"file_path": "/path/to/document.pdf"
}
}
๐ list_supported_formats
Get a complete list of supported file formats.
{
"name": "list_supported_formats",
"arguments": {}
}
๐ convert_directory
Convert all supported files in a directory.
{
"name": "convert_directory",
"arguments": {
"input_directory": "/path/to/files",
"output_directory": "/path/to/markdown"
}
}
๐ Supported File Formats (29+)
| Category | Extensions | Features |
|---|---|---|
| ๐ Office | .pdf, .docx, .pptx, .xlsx, .xls |
Full document structure |
| ๐ผ๏ธ Images | .jpg, .png, .gif, .bmp, .tiff, .webp |
EXIF metadata extraction |
| ๐ต Audio | .mp3, .wav |
Speech-to-text transcription |
| ๐ Web | .html, .htm, .xml, .json, .csv |
Clean formatting |
| ๐ Books | .epub |
Chapter extraction |
| ๐ฆ Archives | .zip |
Auto-extract and process |
| ๐ Text | .txt, .md, .rst |
Direct conversion |
Installation
Published on PyPI as
trsdn-markitdown-mcpโ not to be confused with Microsoft'smarkitdown-mcp.
Option 1: Install from PyPI (Recommended)
# Isolated install with pipx
pipx install trsdn-markitdown-mcp
# Or with pip
pip install trsdn-markitdown-mcp
# Or run without installing (uv)
uvx trsdn-markitdown-mcp
Option 2: Install from source (development)
git clone https://github.com/trsdn/markitdown-mcp.git
cd markitdown-mcp
pip install -e ".[all]"
Option 3: Direct usage from a checkout
cd markitdown-mcp
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
Quick Start
MCP Server Mode (Recommended)
After installation:
# Start the MCP server (for use with MCP clients)
markitdown-mcp
# Equivalent alternatives
trsdn-markitdown-mcp
python -m markitdown_mcp
๐ ๏ธ Installation Options
๐ One-Command Install (Recommended)
Install with ALL dependencies in one command:
# Using pipx (recommended)
pipx install trsdn-markitdown-mcp && \
pipx inject trsdn-markitdown-mcp 'markitdown[all]' openpyxl xlrd pandas pymupdf pdfplumber pytesseract pydub speechrecognition
# Or download and run the install script
curl -sSL https://raw.githubusercontent.com/trsdn/markitdown-mcp/main/scripts/install-all-deps.sh | bash
Quick Install (Basic Features Only)
pip install trsdn-markitdown-mcp
Complete Install with All Dependencies (Step by Step)
To ensure all file formats are supported, use one of these methods:
Method 1: Using pipx (Recommended)
# Install the MCP server
pipx install trsdn-markitdown-mcp
# Install all required dependencies for full functionality
pipx inject trsdn-markitdown-mcp 'markitdown[all]' # PDF, OCR, Speech
pipx inject trsdn-markitdown-mcp openpyxl xlrd pandas # Excel support
pipx inject trsdn-markitdown-mcp pymupdf pdfplumber # Advanced PDF
Method 2: Using pip with virtual environment
# Create and activate virtual environment
python -m venv markitdown-env
source markitdown-env/bin/activate # On Windows: markitdown-env\Scripts\activate
# Install with all dependencies in one command
git clone https://github.com/trsdn/markitdown-mcp.git
cd markitdown-mcp
pip install -e ".[all]" # This installs everything!
Method 3: For Claude Desktop with existing installation
If you already have the MCP server installed but some formats aren't working:
# Find your installation
which markitdown-mcp # Shows path like /Users/you/.local/bin/markitdown-mcp
# Inject missing dependencies
pipx inject trsdn-markitdown-mcp 'markitdown[all]' openpyxl xlrd pandas pymupdf pdfplumber
Verify Installation
After installation, verify the server responds to MCP requests:
# Ask the server for its tool list over stdio (JSON-RPC)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | markitdown-mcp
# For pipx installations, check injected packages
pipx list --include-injected
๐ง Claude Desktop Configuration
Add this to your Claude Desktop claude_desktop_config.json:
{
"mcpServers": {
"markitdown": {
"command": "markitdown-mcp",
"args": []
}
}
}
Prefer running it without a permanent install? Use uvx (the package name is
trsdn-markitdown-mcp, the command is markitdown-mcp):
{
"mcpServers": {
"markitdown": {
"command": "uvx",
"args": ["trsdn-markitdown-mcp"]
}
}
}
Config file locations:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
๐ก Usage Examples
Convert a PDF
Convert the file ~/Documents/report.pdf to markdown
Batch Process Directory
Convert all files in ~/Downloads/documents/ to markdown
Check Supported Formats
What file formats can you convert to markdown?
๐ Troubleshooting
Missing Dependencies Errors
If you see errors like:
PdfConverter threw MissingDependencyExceptionXlsxConverter threw MissingDependencyExceptionPptxConverter threw BadZipFile
This means some optional dependencies are missing. Follow the Complete Install instructions above.
Unicode Errors with .md Files
Some Markdown files with special characters may fail with UnicodeDecodeError. This is a known limitation in the MarkItDown library.
Installation Issues
- "externally-managed-environment" error: Use pipx instead of pip
- Permission denied: Never use sudo with pip; use pipx or virtual environments
- Command not found: Make sure
~/.local/binis in your PATH
See KNOWN_ISSUES.md for more details.
Configuration
No special configuration required. The tool uses the MarkItDown library for document conversion.
Usage
Basic Usage
# Convert all supported files from input/ to output/
python mdconvert.py
Custom Directories
Specify custom input and output directories:
python mdconvert.py --input /path/to/docs --output /path/to/markdown
Single File Conversion
Convert a single file:
python mdconvert.py --file document.pdf
Command Line Options
--input, -i: Input directory (default:input)--output, -o: Output directory (default:output)--file, -f: Convert a single file instead of a directory
MCP Server Features
The MCP server provides three tools:
1. convert_file
Convert a single file to Markdown.
- Input: File path or base64 encoded content with filename
- Output: Converted Markdown content
2. list_supported_formats
List all supported file formats.
- Output: Categorized list of supported file extensions
3. convert_directory
Convert all supported files in a directory.
- Input: Input directory path, optional output directory
- Output: Summary of conversion results
Directory Structure
markitdown-mcp/
โโโ mcp_server.py # MCP protocol server
โโโ mdconvert.py # CLI script
โโโ mcp_config.json # MCP configuration
โโโ requirements.txt # Python dependencies
โโโ README.md # This file
โโโ input/ # Default input directory
โโโ output/ # Default output directory
โโโ venv/ # Virtual environment
๐ How It Works
This MCP server leverages Microsoft's MarkItDown library to provide intelligent document conversion:
- ๐ PDFs: Extracts text, tables, and structure
- ๐ผ๏ธ Images: Uses OCR to extract text content + EXIF metadata
- ๐ต Audio: Converts speech to text transcription (MP3, WAV)
- ๐ Office: Preserves formatting from Word, Excel, PowerPoint
- ๐ HTML: Converts to clean, readable Markdown
- ๐ฆ Archives: Automatically extracts and processes contents
๐ท๏ธ Tags
mcp model-context-protocol claude-desktop markdown document-conversion pdf ocr speech-to-text markitdown ai-tools
๐ Requirements
- Python: 3.10+
- MCP Client: Claude Desktop or compatible MCP client
- Dependencies: Automatically installed via pip
๐ค Contributing
We welcome contributions! Here's how you can help:
๐ Quick Start for Contributors
# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/markitdown-mcp.git
cd markitdown-mcp
# Set up development environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
# Test your changes
markitdown-mcp # Test the server works
๐ Ways to Contribute
- ๐ Bug Reports: Found an issue? Report it
- ๐ก Feature Requests: Have an idea? Suggest it
- ๐ New File Formats: Add support for more file types
- ๐ Documentation: Improve guides and examples
- ๐งช Testing: Add tests and improve reliability
- ๐จ Code Quality: Refactor and optimize
๐ Contribution Process
- Read our Contributing Guide
- Check existing issues
- Fork the repository
- Create a feature branch (
feat/amazing-feature) - Make your changes with tests
- Submit a pull request
Please read docs/development/CONTRIBUTING.md for detailed guidelines.
๐ Documentation
For Users
- Examples - MCP client configuration examples
- Known Issues - Common problems and solutions
- Changelog - Version history and updates
For AI Agents
- AGENTS.md - Comprehensive guide for AI agent integration
- API Documentation - Technical specifications and tool details
For Developers
- Contributing Guide - How to contribute
- Testing Strategy - Testing approach and guidelines
- Documentation - Complete documentation index
Project facts
- Status and maintenance: beta, maintained by @trsdn. Report problems through issues; security reports follow the security policy.
- Language: primary language English, English only. The server has no localized strings.
- Privacy: the server reads only files it is asked to convert, from the safe directories it allows (the Documents, Downloads and Desktop folders in the home directory, temporary directories, the working directory, and
MARKITDOWN_SAFE_DIRS), and writes only to the output directory the caller names. It collects no data, sends no telemetry and contacts no network service itself. The one exception is optional audio transcription: with theallextra installed, thespeechrecognitionpackage sends the audio to Google's web speech recognition service. Nothing is retained after a request beyond the files the caller asked to be written. - Accessibility: there is no graphical interface. The server speaks JSON-RPC over stdio and its log lines go to standard error as plain text. No accessibility limitation is known.
- Third-party code: this repository redistributes none. Dependencies are declared in
pyproject.tomland resolved by the installer when the package is installed.
๐ License
MIT License - see LICENSE file for details.
Repository stats
๐ Related
- Model Context Protocol
- Claude Desktop
- Microsoft MarkItDown# Test workflow fixes