markdownify-mcp MCP — Use Cases, Install & Live Demo

Why use it

Key features

10 converters: PDF, DOCX, XLSX, PPTX, images, audio, YouTube, Bing search, web pages
Uniform tool shape: give a path or URL, get markdown
Audio transcription via OpenAI Whisper-compatible backend
Works with local files and remote URLs
Node-based; stdio transport

Live Demo

What it looks like in practice

markdownify.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "markdownify": {
      "command": "npx",
      "args": [
        "-y",
        "markdownify-mcp"
      ],
      "_inferred": true
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "markdownify": {
      "command": "npx",
      "args": [
        "-y",
        "markdownify-mcp"
      ],
      "_inferred": true
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "markdownify": {
      "command": "npx",
      "args": [
        "-y",
        "markdownify-mcp"
      ],
      "_inferred": true
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "markdownify": {
      "command": "npx",
      "args": [
        "-y",
        "markdownify-mcp"
      ],
      "_inferred": true
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "markdownify",
      "command": "npx",
      "args": [
        "-y",
        "markdownify-mcp"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "markdownify": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "markdownify-mcp"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add markdownify -- npx -y markdownify-mcp

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use markdownify-mcp

How to ingest a folder of PDFs into a markdown knowledge base

👤 RAG builders, knowledge managers ⏱ ~30 min intermediate

When to use: You have 50 PDF research papers and want clean text to embed.

Prerequisites

pnpm — npm i -g pnpm
Install + run — git clone the repo, pnpm install, pnpm start

Flow

Enumerate files

List every .pdf under /library/papers/.✓ Copied

→ Path list
Convert in batch

For each, call pdf-to-markdown. Write the output to /library/markdown/<same-name>.md.✓ Copied

→ Markdown files appear
Spot-check one

Show me the first 500 chars of /library/markdown/attention-is-all-you-need.md.✓ Copied

→ Legible markdown, no PDF artifacts

Outcome: A parallel /markdown/ tree ready to embed.

Pitfalls

Scanned PDFs (image-only) produce empty markdown — Pre-OCR scanned PDFs before conversion
Math-heavy PDFs lose equations — For math, try pairing with Mathpix or the nougat OCR model separately

Combine with: filesystem

How to turn a meeting recording into searchable notes

👤 Anyone recording meetings ⏱ ~10 min beginner

When to use: Post-call, before memory fades.

Prerequisites

OpenAI key for Whisper — platform.openai.com (or any Whisper-compatible endpoint)

Flow

Transcribe

audio-to-markdown on /recordings/2026-04-14-standup.m4a.✓ Copied

→ Markdown with timestamps
Extract actions

From the transcript, list action items with owners.✓ Copied

→ Action checklist

Outcome: Searchable meeting notes + actions.

Pitfalls

Whisper mislabels speakers — For speaker diarization, use a specialized tool; markdownify gives you text only

Combine with: notion

How to summarize a YouTube video without watching it

👤 Researchers, learners ⏱ ~5 min beginner

When to use: A 90-minute video in your feed when you have 5 minutes.

Flow

Pull transcript

youtube-to-markdown https://youtu.be/xyz123.✓ Copied

→ Transcript markdown
Summarize

Summarize in 5 bullets + key timestamps.✓ Copied

→ Bulleted summary with jump points

Outcome: Decision on whether to actually watch the video.

Pitfalls

Some videos have captions disabled — The tool returns empty — fall back to audio-to-markdown if you have the file

Combinations

Pair with other MCPs for X10 leverage

markdownify + filesystem

Batch-convert an inbox folder to a knowledge base folder

Convert every file in /inbox/ to markdown under /kb/ preserving the directory tree.✓ Copied

markdownify + notion

Drop converted docs straight into Notion

Convert the PDF /specs/rfq-2026.pdf and create a Notion page with the result.✓ Copied

markdownify + excel

Combine xlsx-to-markdown with excel MCP for round-tripping

Read /report.xlsx sheet 'Summary', convert to markdown, and save to /docs/report.md.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
pdf-to-markdown	path_or_url: str	Convert PDFs	free (local)
docx-to-markdown	path_or_url: str	Word docs	free
xlsx-to-markdown	path_or_url: str	Spreadsheets as tables	free
pptx-to-markdown	path_or_url: str	Slide decks	free
image-to-markdown	path_or_url: str	Images	free or 1 LLM call if OCR enabled
audio-to-markdown	path: str	Audio/voice memos	1 Whisper call ($0.006/min)
youtube-to-markdown	url: str	YouTube captions	free
webpage-to-markdown	url: str	Readable web text	free
bing-search-to-markdown	query: str	Quick web search	free
get-markdown-file	path: str	Retrieve a prior conversion	free

Cost & Limits

What this costs to run

API quota: None for local converters; Whisper/OpenAI for audio
Tokens per call: Depends on doc size
Monetary: Free except audio transcription (~$0.006/min via Whisper)
Tip: For large PDF batches, do conversion before pasting into the LLM — cheaper than asking Claude to parse PDFs directly.

Security

Permissions, secrets, blast radius

Minimum scopes: Filesystem read on source files, write on output

Credential storage: OPENAI_API_KEY (for audio) in env

Data egress: Local converters stay local. Audio goes to your Whisper endpoint.

Never grant: Don't run untrusted URLs through webpage-to-markdown without sandboxing — SSRF risk

pptx/docx converters occasionally lose formatting; review before using as source of truth.

Troubleshooting

Common errors and fixes

pnpm install fails

Node version too old — requires Node 18+. nvm install 20.

Verify: node -v

pdf-to-markdown returns empty string

Likely a scanned PDF (image-only). Run OCR first (ocrmypdf).

youtube-to-markdown 'no captions available'

Video owner disabled captions. Download audio and use audio-to-markdown instead.

audio-to-markdown 401

Missing or invalid OPENAI_API_KEY.

Verify: echo $OPENAI_API_KEY

Alternatives

markdownify-mcp vs others

Alternative	When to use it instead	Tradeoff
markitdown (Microsoft)	You want the underlying converter directly without MCP	No MCP interface; needs your own wrapping
unstructured.io	Enterprise-scale ingestion with layout awareness	Paid for advanced features

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills