zcaceres/markdownify-mcp: MCP Server for PDF, Audio & Web Conversion

zcaceres/markdownify-mcp: MCP Server for PDF, Audio & Web Conversion

Developers building AI-powered workflows face a persistent friction point: large language models work best with clean, structured text, but the real world delivers PDFs, images, audio recordings, and messy web pages. Converting these formats manually is tedious. Building reliable pipelines is worse. zcaceres/markdownify-mcp solves this by acting as a Model Context Protocol (MCP) server that transforms almost any content into Markdown^{↗ Smart Converter} — the lingua franca of LLM context windows.

What is zcaceres/markdownify-mcp?

zcaceres/markdownify-mcp is an open-source MCP server written in TypeScript and licensed under MIT. With 2,845 GitHub stars and 239 forks as of its last commit on July 9, 2026, it has gained meaningful traction among developers who need robust format conversion without managed-service lock-in.

The project sits at the intersection of two technical trends: the Model Context Protocol (MCP) — Anthropic's open standard for connecting AI assistants to external tools — and the growing need to feed multimodal content into LLM pipelines. Rather than building ad-hoc converters for each format, you deploy one server that exposes standardized tools your MCP-compatible client can call.

The maintainer, zcaceres, designed this as a self-hosted solution. It bundles Microsoft's markitdown library (with optional [all] extras) in a Python^{↗ Bright Coding Blog} virtual environment, wraps it in a TypeScript MCP server runtime using Bun, and exposes ten conversion tools. This architecture matters: you get Python's mature document-processing ecosystem with JavaScript^{↗ Bright Coding Blog}'s async server ergonomics.

Key Features

zcaceres/markdownify-mcp handles three broad content categories:

Document conversion covers PDF, DOCX, XLSX, and PPTX files. These use markitdown under the hood, which preserves structural elements like tables and headings where possible.

Media conversion includes images (with OCR/metadata extraction) and audio files (with transcription to text). These capabilities depend on the [all] extras installation — the Docker^{↗ Bright Coding Blog} slim image only includes [pdf], so audio and image OCR require local installation.

Web content extraction spans YouTube transcripts, Bing search results, and arbitrary web pages. This is particularly useful for research workflows where you need to ground LLM responses in current information without manual copy-pasting.

A retrieval tool, get-markdown-file, reads existing .md or .markdown files, making the server useful as a unified document interface.

Security features include path restriction via MD_ALLOWED_PATHS — a delimiter-separated list of permitted directories that prevents file-input tools from escaping designated boundaries. This matters for multi-tenant or shared environments.

Use Cases

AI assistant augmentation: Connect zcaceres/markdownify-mcp to Claude Desktop, Cursor, or any MCP-compatible client. Your assistant gains the ability to read PDF research papers, transcribe meeting recordings, and analyze spreadsheets without leaving the chat interface.

Documentation pipelines: Convert legacy DOCX specifications or PPTX slide decks into Markdown for static site generators or version-controlled documentation. The structural preservation means less manual reformatting.

Research and competitive intelligence: Pipe Bing search results or YouTube transcripts directly into analysis workflows. The Markdown output is immediately chunkable for RAG (Retrieval-Augmented Generation) systems.

Compliance and audit workflows: Process XLSX financial records or PDF contracts into text for automated extraction, diffing, or archival. The MD_ALLOWED_PATHS restriction ensures read-only access to sensitive directories.

Local-first AI setups: Self-host the entire pipeline with Docker, keeping documents on-premise while still enabling LLM interaction. This addresses data residency requirements that cloud conversion services cannot satisfy.

Installation & Setup

The project requires Bun as its runtime. Python is needed for the markitdown dependency, which the install process handles automatically.

Clone and install dependencies:

git clone https://github.com/zcaceres/markdownify-mcp.git
cd markdownify-mcp
bun install

The preinstall script creates a Python virtual environment at .venv and installs markitdown[all]. This provides the full feature set including audio transcription and image OCR.

Build the TypeScript source:

bun run build

Start the server:

bun start

For development with hot reload:

bun run dev

The server entry point is dist/index.js after building. Key source files to customize are src/server.ts (server behavior) and src/tools.ts (tool definitions).

Desktop app integration

Add to your MCP client's configuration:

{
  "mcpServers": {
    "markdownify": {
      "command": "node",
      "args": [
        "{ABSOLUTE PATH TO FILE HERE}/dist/index.js"
      ]
    }
  }
}

Replace {ABSOLUTE PATH TO FILE HERE} with your actual project path.

Docker deployment

docker build -t markdownify-mcp .
docker run --rm -i \
  -v "$HOME/Documents:/data:ro" \
  -e MD_ALLOWED_PATHS=/data \
  markdownify-mcp

Critical Docker notes: mount host directories read-only (:ro) and pass container paths to tools (e.g., /data/foo.pdf). The published image installs markitdown[pdf] only — audio and image conversion fail without the [all] extras. Build locally or extend the Dockerfile for full capabilities.

Real Code Examples

The README provides two primary configuration patterns. Here's the desktop app integration with environment variables for a system-wide markitdown installation:

{
  "mcpServers": {
    "markdownify": {
      "command": "node",
      "args": [
        "/home/user/projects/markdownify-mcp/dist/index.js"
      ],
      "env": {
        "MARKITDOWN_PATH": "/home/user/.local/bin/markitdown",
        "MD_ALLOWED_PATHS": "/home/user/documents:/home/user/downloads"
      }
    }
  }
}

This configuration uses pipx-installed markitdown instead of the bundled venv, and restricts file access to two directories. The MARKITDOWN_PATH override is necessary when you've installed markitdown system-wide with extras like [pdf] that your use case requires.

The Docker run command with multiple mounted volumes:

docker run --rm -i \
  -v "$HOME/Documents:/docs:ro" \
  -v "$HOME/Downloads:/dl:ro" \
  -e MD_ALLOWED_PATHS=/docs:/dl \
  -p 3000:3000 \
  markdownify-mcp

Here two directories are mounted with colon-separated paths in MD_ALLOWED_PATHS. The server rejects any file request outside these boundaries, implementing a simple but effective sandbox. Note that port exposure (-p 3000:3000) is illustrative — the MCP server communicates over stdio by default, not HTTP.

Advanced Usage & Best Practices

Path hygiene: Always set MD_ALLOWED_PATHS in production, even for single-user setups. The default unrestricted mode is convenient for development but risky with file-input tools.

Feature parity between install methods: If you need audio transcription or image OCR, the local bun install path is currently the only reliable option. The Docker slim image's [pdf]-only markitdown installation is a deliberate size optimization that trades capability for image size. Consider building a custom image with markitdown[all] if Docker is non-negotiable.

Tool selection strategy: The ten available tools overlap partially — webpage-to-markdown handles general URLs, while youtube-to-markdown and bing-search-to-markdown optimize for specific formats. Use the specialized tools when available; they likely handle edge cases (like YouTube's transcript availability checks) more gracefully.

Monitoring conversion quality: markitdown excels at structure preservation but can struggle with complex layouts. For critical documents, validate output against source formatting, particularly for tables in PDFs and merged cells in spreadsheets.

Comparison with Alternatives

zcaceres/markdownify-mcp occupies a specific niche: developers who want MCP-native tool calling without vendor lock-in, and who can tolerate self-hosting overhead for data control. Pandoc offers more output formats but requires custom integration work. Direct MarkItDown usage skips the protocol layer entirely. Cloud services reduce operational burden at a privacy and cost trade-off.

FAQ

Q: What runtime does zcaceres/markdownify-mcp require? A: Bun for the TypeScript server, plus Python for the markitdown dependency.

Q: Can I use this without installing Python manually? A: Yes — bun install creates .venv and installs Python dependencies automatically.

Q: Why does audio-to-markdown fail in Docker? A: The published image only includes markitdown[pdf]. Use local installation or rebuild with [all] extras.

Q: Is this free for commercial use? A: Yes, MIT licensed. No restrictions stated in the repository.

Q: How do I restrict which files the server can read? A: Set MD_ALLOWED_PATHS to a delimiter-separated list of permitted directories.

Q: Can I modify the available tools? A: Yes — edit src/tools.ts and rebuild with bun run build.

Q: Does this work with Claude Desktop? A: Yes, via standard MCP server configuration in the client's settings.

Conclusion

zcaceres/markdownify-mcp is a pragmatic solution for developers who need multimodal content in Markdown format without surrendering data to third-party APIs. Its 2,845 stars reflect genuine utility in the MCP ecosystem, not marketing hype. The self-hosted model suits privacy-conscious teams, air-gapped environments, and anyone building local-first AI workflows.

The tool is best suited for: developers already using MCP-compatible clients, teams with mixed document pipelines, and organizations where data residency matters. It is less ideal for those seeking zero-configuration SaaS or who rarely need format conversion.

If your LLM workflows are bottlenecked by PDFs, audio files, or web content that won't fit cleanly into a context window, explore zcaceres/markdownify-mcp on GitHub and evaluate whether its toolset matches your conversion needs.

For related MCP server patterns, see [INTERNAL_LINK: model-context-protocol-guide].