Repository navigation
Markitdown MCP
Install and configure the Microsoft MarkItDown MCP server to convert documents, PDFs, images, web pages, and other file types to markdown format.
The MarkItDown MCP server is a Python-based Model Context Protocol (MCP) server that provides a single tool: convert_to_markdown(uri). It can convert:
- Documents: PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx)
-
Web pages: HTML from
http://andhttps://URIs - Images: PNG, JPG, JPEG, GIF, WebP, BMP (with OCR support via Azure)
-
Local files: Via
file://URIs - Data URIs: Embedded data
- Python ≥ 3.10
- pip (Python package manager)
pip install markitdown-mcpVerify the installation:
python3 -m markitdown_mcp --helpYou should see the help output with options like --http, --host, --port.
For IDE integrations (Claude Desktop, Cursor, Cline):
python3 -m markitdown_mcpFor use with OmniRoute or other HTTP-based MCP clients:
python3 -m markitdown_mcp --http --host 127.0.0.1 --port 3001This starts an HTTP server at http://127.0.0.1:3001 with both Streamable HTTP and SSE transports.
The easiest way to test the markitdown-mcp server is using the MCP Inspector:
# In one terminal, start the markitdown-mcp HTTP server
python3 -m markitdown_mcp --http --port 3001
# In another terminal, launch the MCP Inspector
npx @modelcontextprotocol/inspectorIn the Inspector UI:
- Select Streamable HTTP as the transport type
- Enter
http://127.0.0.1:3001/mcpas the URL - Click Connect
- Navigate to the Tools tab
- Click List Tools to see
convert_to_markdown - Test the tool by providing a URI (e.g.,
https://example.com,file:///path/to/file.pdf)
Edit your claude_desktop_config.json to use the STDIO transport:
macOS/Linux: ~/.claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"markitdown": {
"command": "python3",
"args": ["-m", "markitdown_mcp"]
}
}
}Restart Claude Desktop and the tool will be available.
Build and run the Docker image:
# Clone the Microsoft markitdown repository
git clone https://github.com/microsoft/markitdown.git
cd markitdown/packages/markitdown-mcp
# Build the Docker image
docker build -t markitdown-mcp:latest .
# Run the server
docker run -it --rm markitdown-mcp:latestTo mount local files:
docker run -it --rm -v /home/user/documents:/workdir markitdown-mcp:latestThen reference files as file:///workdir/filename.pdf.
The markitdown-mcp server:
- Does not support authentication — runs with the privileges of the user executing it
- Has unrestricted file access — can read any file accessible to the user running the server
- Can make network requests — can fetch any URL from the network
-
Should run locally only — binds to
127.0.0.1by default, do NOT bind to0.0.0.0unless you understand the security implications
- Run in a restricted environment — use a dedicated user account with minimal permissions
- Use containers — run in Docker with limited mounts and network access
- Limit scope — restrict input URIs to trusted sources (e.g., internal documents only)
- Monitor execution — log and audit all conversions in production use
https://example.com/document.pdf
https://docs.microsoft.com/en-us/windows/windows-11/
file:///home/user/documents/report.docx
file:///Users/jane/Downloads/presentation.pptx
file://C:\\Users\\User\\Documents\\spreadsheet.xlsx (Windows)
data:text/plain;base64,SGVsbG8gV29ybGQ=
{
"uri": "https://example.com/document.pdf"
}The tool returns the converted markdown as a string, so it arrives as MCP text content:
{
"content": [{ "type": "text", "text": "# Document Title\n\nContent converted to markdown..." }],
"isError": false
}A failed conversion is reported as an MCP tool error:
{
"content": [{ "type": "text", "text": "Failed to fetch resource: 404 Not Found" }],
"isError": true
}Configure markitdown-mcp behavior via environment variables:
For enhanced OCR on documents and images:
export AZURE_ENDPOINT="https://your-resource.cognitiveservices.azure.com/"
export AZURE_API_KEY="your-api-key"export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1"If you see ModuleNotFoundError: No module named 'markitdown_mcp':
# Ensure the package is installed
pip3 install markitdown-mcp
# Try using the full path to Python
python3 -m markitdown_mcp --helpIf you encounter cryptography-related errors:
# Install build dependencies
pip3 install --upgrade cffi cryptography
# Or create a fresh virtual environment
python3 -m venv markitdown-env
source markitdown-env/bin/activate
pip install markitdown-mcp
python3 -m markitdown_mcp --httpIf the server cannot fetch remote URLs:
- Check your network connectivity:
curl https://example.com - Verify proxy settings (see Environment Variables section)
- Check firewall rules and corporate proxies
If the server cannot read local files:
- Verify the file path is correct and the file exists:
ls -la /path/to/file - Check file permissions:
chmod 644 /path/to/file - Ensure the server is running with a user that has read access
Large PDF conversions can consume significant memory. If you encounter out-of-memory errors:
- Process files one at a time (avoid parallel batch conversions)
- Run in a container with memory constraints
The HTTP endpoint speaks MCP, so a client has to send initialize and
notifications/initialized before tools/call. Use MCP Inspector or any MCP client rather than
a single curl request. These are the convert_to_markdown arguments for common inputs.
{ "uri": "https://example.com/whitepaper.pdf" }{ "uri": "file:///home/user/screenshot.png" }{ "uri": "https://docs.python.org/3/library/asyncio.html" }- Microsoft MarkItDown Repository: https://github.com/microsoft/markitdown
- MarkItDown MCP Package: https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp
- MCP Protocol: https://modelcontextprotocol.io/
- MCP Inspector: https://github.com/modelcontextprotocol/inspector
For issues with markitdown-mcp:
- GitHub Issues: https://github.com/microsoft/markitdown/issues
- PyPI Package: https://pypi.org/project/markitdown-mcp/
For OmniRoute integration questions, refer to the main OmniRoute documentation at docs/frameworks/MCP-SERVER.md.
OmniRoute · Website · npm · Docker Hub
- Setup Guide
- User Guide
- Features
- Quick Start (Docker)
- Electron Desktop App
- Termux (Android)
- PWA Guide
- MCP Server
- A2A Server
- Agent Protocols
- OpenCode Plugin
- Webhooks
- Cloud Agents
- Skills
- Memory
- Evals
- Gamification
- Guardrails
- Compliance
- Error Sanitization
- Public Credentials
- Route Guard Tiers
- Stealth Guide
- CLI Token Auth