Overview

Markitdown MCP Server converts arbitrary files into Markdown so downstream systems (search, indexing, ingestion pipelines, and editors) can consume consistent, text-first content. Built as an MCP (Model Context Protocol) server, Markitdown is designed to sit between file storage and large language models or vector stores: it extracts text, preserves structure (headings, lists, links), and optionally performs OCR on images and scanned PDFs. The result is machine-friendly Markdown suitable for chunking, embedding, or human editing.

The server supports both single-file and batch operations and exposes a simple HTTP API for integration. It is optimized for batch workflows and high-throughput pipelines: configurable concurrency, chunking, and output options let you balance accuracy, file-size limits, and latency.

Features

File-to-Markdown conversion across common document formats (PDF, DOCX, PPTX, HTML, TXT, RTF)
OCR support for images and scanned PDFs (PNG, JPG, TIFF)
Preserves document structure: headings, lists, links, code blocks, and tables
Batch processing mode for directories and queued workloads
Configurable chunking to produce context windows suitable for LLMs and embedding pipelines
HTTP API compatible with MCP patterns for easy orchestration
Output options: raw Markdown, front-matter metadata, or split/chunked artifacts
Concurrency and resource controls for high-throughput environments
Health and metrics endpoints for integration with monitoring systems

Installation / Configuration

Clone the repository and run with Docker or Python. The server reads environment variables or a YAML config for runtime options.

Clone repository:

git clone https://github.com/Klavis-AI/klavis.git
cd klavis/mcp_servers/markitdown

Run with Docker:

docker build -t markitdown .
docker run -p 8080:8080 \
  -e PORT=8080 \
  -e INPUT_DIR=/data/in \
  -e OUTPUT_DIR=/data/out \
  -v /local/in:/data/in \
  -v /local/out:/data/out \
  markitdown

Python / virtualenv:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m markitdown.server --config config.yaml

Example config.yaml:

server:
  host: 0.0.0.0
  port: 8080
convert:
  ocr: true
  chunk_size: 1000
  chunk_overlap: 200
  max_file_size_mb: 200
concurrency:
  workers: 4
logging:
  level: info

Common environment variables

PORT: server port (default 8080)
INPUT_DIR / OUTPUT_DIR: local volume paths for batch processing
MAX_CONCURRENCY or WORKERS: parallel file processors
OCR: enable/disable OCR pipeline

Available Resources

HTTP endpoints (examples; adapt to your deployment path):

Endpoint	Method	Description
/health	GET	Returns server health and readiness
/convert	POST	Convert a single file (multipart/form-data)
/batch	POST	Start batch conversion on a directory or list of file URLs
/status/{id}	GET	Check progress of an async batch job
/metrics	GET	Prometheus-style metrics (if enabled)

Example: convert a single file with curl

curl -X POST "http://localhost:8080/convert" \
  -F "file=@/path/to/document.pdf" \
  -F "ocr=true" \
  -o result.md

Batch invocation (JSON body):

curl -X POST "http://localhost:8080/batch" \
  -H "Content-Type: application/json" \
  -d '{"input_dir":"/data/in","output_dir":"/data/out","recursive":true}'

Use Cases

Ingesting corporate PDFs into a semantic search index
- Batch-convert a directory of reports to Markdown, chunk by 1,000 tokens, then feed chunks to an embedding pipeline for a vector DB.
Digitizing scanned documents with OCR
- Upload a folder of scanned invoices (TIFF/JPG). Enable OCR to extract text and preserve tables for downstream reconciliation.
Preparing content for static site generators
- Convert mixed DOCX/HTML/MD source content to standardized Markdown with front-matter, ready for Hugo or Jekyll.
Preprocessing content for LLM prompting
- Convert and chunk large manuals into consistent Markdown sections so prompts can include precise context windows without manual editing.
Archiving and compliance workflows
- Normalize diverse document types into readable, searchable Markdown files for long-term storage and e-discovery.

Tips and Best Practices

Tune chunk_size and overlap to match your LLM context window and embedding service limits.
Enable OCR only when necessary—OCR increases CPU usage and latency.
For large batch jobs, mount input/output as volumes and monitor /metrics for throughput and error rates.
Validate outputs on a small sample before processing large archives to ensure format and metadata meet downstream expectations.

For code examples and the latest configuration options, see the repository: https://github.com/Klavis-AI/klavis/tree/main/mcp_servers/markitdown

Markitdown MCP Server: Convert Files to Markdown