markdownify-mcp

Implements a Model Context Protocol server that registers conversion tools as callable endpoints and routes incoming tool-call requests to appropriate handlers. The server uses TypeScript/Node.js to expose a standardized MCP interface that clients can discover via list-tools and invoke via call-tool, with Zod schema validation for all input parameters before routing to the Markdownify core engine.

Converts PDF files to Markdown by delegating to the Python markitdown library, which extracts text, tables, and structural metadata from PDF documents and formats them as semantic Markdown. Handles both local file paths and remote URLs, manages temporary file storage for URL-sourced PDFs, and preserves document structure including headings, lists, and table formatting.

Executes the Python markitdown tool as a subprocess, managing the Python environment through the uv package manager for dependency isolation and reproducible builds. The Markdownify class spawns the markitdown process with input file path and captures stdout/stderr, handling subprocess lifecycle, error codes, and output parsing without requiring system-wide Python installation.

Validates all tool parameters using Zod schemas before passing to conversion handlers, ensuring type safety and preventing invalid inputs from reaching the Python subprocess. The MCP server layer defines schemas for each tool (e.g., URL format, file path existence) and validates incoming requests, returning detailed error messages for validation failures without executing conversions.

Converts Microsoft Office formats (Word, Excel, PowerPoint) to Markdown by delegating to markitdown's Python handlers, which parse the Office Open XML structure and extract text, tables, slides, and formatting metadata. Supports both local files and remote URLs, with temporary file management for URL sources and preservation of document structure including nested tables and multi-slide presentations.

Converts HTML web pages to Markdown by fetching the page via HTTP(S), parsing the DOM structure, and extracting semantic content while removing boilerplate (navigation, ads, scripts). The markitdown Python library uses BeautifulSoup or similar HTML parsing to identify main content, preserve heading hierarchy, convert links to Markdown syntax, and format lists and tables appropriately.

Converts YouTube videos to Markdown by fetching the video transcript (via YouTube's API or transcript extraction library) and formatting it as readable Markdown with timestamps and speaker labels. The markitdown library handles transcript retrieval and formatting, preserving temporal structure and converting timestamps to Markdown comments or inline references.

Converts images (PNG, JPG, etc.) to Markdown by performing optical character recognition (OCR) to extract text content and generating alt-text descriptions. The markitdown library integrates with Python OCR engines (likely Tesseract or similar) to extract text from images and optionally uses vision models to generate semantic descriptions, embedding results as Markdown code blocks or alt-text attributes.

Converts audio files (MP3, WAV, etc.) to Markdown by transcribing speech to text using Python speech-to-text libraries (likely Whisper or similar). The markitdown library handles audio format detection, transcription, and optional speaker diarization, outputting transcribed text with timestamps and speaker labels formatted as Markdown.

Converts Bing search results into a compiled Markdown document by querying Bing Search API, fetching the top N results, extracting content from each result page, and aggregating them into a single Markdown file with source attribution. The markitdown library handles search query execution, result ranking, and content extraction from each result, with links and citations preserved in Markdown format.

Accepts existing Markdown files and validates them for correctness, optionally normalizing formatting (heading levels, list indentation, code fence syntax). The Markdownify class detects Markdown input by file extension or content inspection and either passes through the content unchanged or applies optional normalization rules, ensuring consistent Markdown formatting across converted and native Markdown sources.

Manages the lifecycle of temporary files created when processing remote URLs, downloading content to a temp directory, passing the file path to the markitdown Python tool, and cleaning up after conversion completes. The Markdownify class handles temp directory creation, file naming, cleanup on success/failure, and error handling for disk space issues, abstracting file system complexity from the conversion logic.