Markdownify MCP Server
Author: zcaceres
Description: An MCP (Model Context Protocol) server that converts many file types and web content into Markdown (PDF, images/OCR, audio transcription, DOCX/XLSX/PPTX, webpages, YouTube transcripts, Bing search results) and can retrieve existing .md/.markdown files. Typical setup: pnpm install → pnpm run build → pnpm start (Bun is used to run dist/index.js). Optional env: UV_PATH for uv location; MD_SHARE_DIR to restrict markdown file retrieval directory.
Stars: 2.4k
Forks: 202
License: MIT License
Category: Open Source
Overview
Installation
3. Build the project:```
pnpm run build
Development:
- Start the TypeScript compiler in watch mode:```
pnpm run dev{
"mcpServers": {
"markdownify": {
"command": "node",
"args": [
"{ABSOLUTE PATH TO FILE HERE}/dist/index.js"
],
"env": {
// By default, the server will use the default install location of `uv`
"UV_PATH": "/path/to/uv"
}
}
}
}youtube-to-markdown
Convert YouTube videos to Markdown (includes extracting the video transcript).
pdf-to-markdown
Convert PDF files to Markdown.
bing-search-to-markdown
Convert Bing search results to Markdown.
webpage-to-markdown
Convert general web pages to Markdown.
image-to-markdown
Convert images to Markdown with metadata.
audio-to-markdown
Convert audio files to Markdown with transcription.
docx-to-markdown
Convert DOCX files to Markdown.
xlsx-to-markdown
Convert XLSX files to Markdown.
pptx-to-markdown
Convert PPTX files to Markdown.
get-markdown-file
Retrieve an existing Markdown file (must end with .md or .markdown); can be restricted to a directory via the MD_SHARE_DIR environment variable.
FAQs
Can Markdownify MCP Server handle large PDF files or batch conversions of multiple documents at once?
The content does not specify file-size limits or batch-processing capabilities for Markdownify's PDF tool. Each of the ten tools appears to accept individual files per invocation, so batch workflows would require sequential calls from the MCP client or custom scripting. Performance on large PDFs depends on the underlying Python conversion libraries, which are not detailed in the repository documentation.
Does Markdownify MCP Server support running under WSL2 on Windows, and how do I set it up?
Yes, WSL2 is mentioned as a practical workaround when native Windows setup fails. The content does not provide WSL2-specific installation steps, but the standard Linux setup applies: install uv and Node.js inside your WSL2 distribution, clone the repo, build with pnpm, then configure your MCP client using WSL2 file paths and ensure the client can access the WSL2 environment.
How do I fix Markdownify MCP Server connection failures on Windows?
Windows support is experimental and unverified by maintainers. When native setup fails, run Markdownify under WSL2, which provides a Linux environment where Node.js MCP and Python uv operate predictably. Alternatively, ensure absolute paths in client config use forward slashes and uv is accessible from Windows PATH.
How do I configure Markdownify MCP Server with Claude Desktop step by step?
Install uv and Node.js with pnpm, clone the repository, run pnpm install and pnpm run build. Open Claude Desktop's configuration file, locate mcpServers, and add a markdownify entry with node as command, absolute path to dist/index.js in args, and UV_PATH pointing to your uv binary in env. Restart Claude Desktop.
What are the most common issues faced when setting up an MCP server?
Common MCP server setup issues include incorrect registry URLs with extra path segments, disabled anonymous access causing silent failures, missing runtime prerequisites, OAuth authorization errors needing endpoint verification, and permission rejections despite valid tokens. Configuration precision around base endpoints, org-level feature enablement, and exponential backoff retry logic are critical for connectivity.
What are the best practices for securing an MCP server?
General MCP server security follows principle-of-least-privilege patterns: restrict tool access via allow-lists, sandbox file system operations to specific directories using environment variables, isolate network-facing tools with firewall rules, validate all inputs rigorously, run the server under non-privileged user accounts, and enable audit logging for tool invocations to detect misuse across shared environments.