Overview

Markdownify MCP Server is a lightweight Model Context Protocol (MCP) server that converts a variety of input media into clean, structured Markdown. It is designed for developers and teams that need to transform slide decks (PPTX), PDFs, HTML pages, YouTube transcripts and similar content into Markdown for documentation, search indexing, or AI context windows. The server focuses on reliable, repeatable extraction: preserving headings, slide/section boundaries, speaker notes, and embedded images as separate assets.

Running as a standalone HTTP service, the server accepts uploads or remote URLs and returns Markdown plus optional extracted resources (images, attachments, metadata). This makes it easy to integrate the conversion step into pipelines that prepare training/response context for language models, generate static documentation, or migrate content into CMSs and knowledge bases.

Features

Convert PPTX, PDF, and HTML to Markdown with preserved structure (titles, lists, paragraphs).
Extract slide-level data: titles, speaker notes, and slide-level images for PPTX.
Pull YouTube transcripts (when available) and render them as time-stamped Markdown.
Accept both file uploads and remote URLs.
Return Markdown with accompanying assets (images, attachments) and metadata JSON.
Lightweight HTTP API suitable for local deployment, CI/CD pipelines, or containerized environments.
Configurable logging, concurrency limits, and temporary storage cleanup.

Installation / Configuration

The project can be run with Docker (recommended) or installed from source. Replace with the GitHub repository URL.

Using Docker (quick start)

# Pull and run (example)
docker run --rm -p 8080:8080 zcaceres/mcp-markdownify-server:latest

# Or build locally and run
git clone https://github.com/zcaceres/mcp-markdownify-server.git
cd mcp-markdownify-server
docker build -t mcp-markdownify-server .
docker run --rm -p 8080:8080 mcp-markdownify-server

Install from source (if the repo provides a Python/Node package)

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

# Python (example)
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m markdownify_server.app --host 0.0.0.0 --port 8080

Configuration (env vars or CLI)

PORT=8080                 # HTTP port to listen on
LOG_LEVEL=info            # debug | info | warn | error
TMP_DIR=/tmp/mcp          # temp file working directory
CONCURRENCY=4             # parallel conversion workers
KEEP_ASSETS=false         # retain extracted images/assets after response

API — Quick Examples

The server exposes an HTTP API that accepts either a file upload or a JSON body specifying a remote URL. Below are example requests—adapt the endpoint path to your deployed server.

Upload a local file (curl)

curl -X POST "http://localhost:8080/convert" \
  -F "[email protected]" \
  -F "format=markdown" \
  -o output.json

Send a remote URL to convert

curl -X POST "http://localhost:8080/convert" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/report.pdf","format":"markdown"}' \
  -o result.json

Python client example

import requests
r = requests.post(
    "http://localhost:8080/convert",
    files={"file": open("slides.pptx","rb")},
    data={"format":"markdown"}
)
result = r.json()
print(result["markdown"][:1000])

Responses typically include:

markdown: the converted Markdown string
assets: list of extracted images/attachments (URLs or base64)
metadata: source filename, page/slide count, conversion warnings/errors

Available Resources

GitHub repository: https://github.com/zcaceres/mcp-markdownify-server
Model Context Protocol (MCP): refer to MCP docs/spec your organization uses for context ingestion
Common tools used in conversions: pandoc, unoconv, pdfminer/PoDoFo, python-pptx, html-to-markdown libraries, YouTube transcript utilities (may be used internally depending on implementation)

Use Cases

AI context generation: Convert slide decks and long PDFs into compact Markdown that can be chunked and fed into language models as context.
Knowledge base migration: Migrate materials from PPTX and HTML into Markdown-based documentation sites (e.g., MkDocs, Hugo).
Content repurposing: Turn presentations and reports into blog drafts or release notes with preserved headings and images.
Search indexing: Normalize mixed-format documents into Markdown for consistent indexing and snippet generation.
Transcript publishing: Convert YouTube transcripts into readable, time-stamped Markdown for accessibility and archiving.

Example workflow: nightly job downloads newly uploaded slide decks from a bucket, posts each file to the MCP server, receives Markdown + asset links, and commits the results to a documentation repo for CI publishing.

Supported Input Formats (summary)

Input type	Output behavior
PPTX	Slide headers, bullet lists, speaker notes, images as separate assets
PDF	Text extraction, page separation, inline images or assets
HTML	Converts DOM structure to headings, lists, links; extracts inline images
YouTube	Pulls available transcript, outputs time-stamped Markdown
Generic URL	Fetches and converts based on content type (HTML/PDF)

Troubleshooting & Tips

Ensure the server has sufficient memory for large PDFs and PPTX files; increase TMP_DIR if conversions fail due to disk space.
If images are missing, check KEEP_ASSETS and the server’s permission to write to the assets directory.
For production, run behind a reverse proxy (nginx) and configure TLS; enforce request size limits to avoid abuse.

For full implementation details, endpoint documentation, and advanced configuration, see the repository README and source code on GitHub.

Tags:media

Markdownify MCP Server: PPTX, PDF, HTML to Markdown