Convert documents to Markdown using MarkItDown
Valid MCP server (1 strong, 4 medium validity signals). No known CVEs in dependencies. Imported from the Official MCP Registry.
6 files analyzed ยท No issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
From the project's GitHub README.
Give your AI assistant the ability to read PDFs, Office files, spreadsheets, emails, audio, and more as clean Markdown โ so it can summarize, search, and reason over content instead of struggling with binary attachments.
Document Converter MCP is a lightweight stdio server that wraps Microsoft's MarkItDown library for the Model Context Protocol.
flowchart LR
A[Your file on disk] --> B[Document Converter MCP]
B --> C[MarkItDown]
C --> D[Markdown in chat or .md file]
| Registry | io.github.Zahid-Abbas-Ali-Baig/document-converter |
| Repository | https://github.com/Zahid-Abbas-Ali-Baig/document-converter |
| Transport | stdio |
| Author | Zahid Abbas Ali Baig |
| Dependencies | markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription] |
Once connected, your agent converts files locally and returns structured text โ nothing is sent to a conversion API.
| Scenario | What you gain |
|---|---|
| Research | Turn PDF papers into Markdown, then ask for summaries, comparisons, or citations |
| Documentation | Convert .docx / .pptx drafts into .md beside the source for wikis or Git |
| Product & engineering | Preview specs and slide decks in chat before writing tickets or release notes |
| Data & ops | Convert Excel exports into tables the model can filter, explain, or transform |
| Email & archives | Extract text from .msg Outlook files or ZIP contents without manual copy-paste |
| Media | Transcribe .mp3 / .wav or fetch YouTube captions into editable Markdown |
.msg, audio, YouTube, and more (via MarkItDown)Formats below are verified against MarkItDown 0.1.6 with our installed extras:
markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]
We avoid markitdown[all] because it pulls Azure pre-release packages that uv cannot resolve with uvx.
| Category | Extensions / inputs | What you get |
|---|---|---|
.pdf | Text and layout extraction ([pdf] extra) | |
| Word | .docx only | Headings, paragraphs, tables ([docx] โ not legacy .doc) |
| PowerPoint | .pptx only | Slide text and structure ([pptx] โ not legacy .ppt) |
| Excel | .xlsx, .xls | Workbook tables ([xlsx] / [xls]) |
| Outlook | .msg | Headers, body, metadata ([outlook]) |
| Web | .html, .htm | HTML โ Markdown (built-in) |
| CSV | .csv | Markdown tables (built-in) |
| Text & JSON | .txt, .md, .json, .jsonl | Plain text / JSON content (built-in) |
| Notebooks | .ipynb | Notebook cells as Markdown (built-in) |
| E-books | .epub | Chapter HTML โ Markdown (built-in) |
| Archives | .zip | Each inner file converted if its type is supported (built-in) |
| Audio | .mp3, .wav, .m4a | Metadata + speech transcription ([audio-transcription]) |
| YouTube | https://www.youtube.com/watch?v=... | Title, description, captions when available ([youtube-transcription]) |
| Category | Extensions | Reality |
|---|---|---|
| Images | .jpg, .jpeg, .png only | EXIF metadata if exiftool is on your PATH; no built-in OCR in this MCP server (MarkItDown can describe images only when an LLM client is configured, which we do not set up) |
| XML | .xml | May work as plain text depending on file detection โ not a dedicated XML parser |
| Other URLs | Wikipedia, RSS, Bing SERP | MarkItDown can fetch some web URLs; not tested as part of this MCP |
| Item | Why |
|---|---|
.eml | No MarkItDown converter for RFC 822 .eml files |
.gif, .webp, .bmp, โฆ | Image converter only accepts .jpg / .jpeg / .png |
| Legacy Office | .doc, .ppt โ use .docx / .pptx |
| Video files | .mp4 etc. โ not converted as video (audio track may work in some cases via the audio converter) |
| Azure Document Intelligence | Needs markitdown[az-doc-intel] + Azure endpoint |
| Azure Content Understanding | Pre-release package; breaks uvx resolution |
markitdown[all] | Bundles the Azure extras above |
Conversion quality depends on the source file. See the MarkItDown documentation for upstream details.
Follow the steps for your editor. Every config below uses the same command โ only the JSON file and wrapper key differ.
Install uv (includes uvx).
Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Verify uvx works (open a new terminal after installing):
uvx --version
Optional โ test the server (it will sit idle with no output; that is normal for stdio MCP):
uvx --from git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter --with markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription] document-converter-mcp
Press Ctrl+C to stop.
%USERPROFILE%\.cursor\mcp.json~/.cursor/mcp.json~/.cursor/mcp.json.cursor/mcp.json in your project foldermcpServers (copy the whole JSON):{
"mcpServers": {
"document-converter": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter",
"--with",
"markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]",
"document-converter-mcp"
]
}
}
}
document-converter should show enabled (green). Tools: convert_to_markdown, preview_markdown.cursor://anysphere.cursor-deeplink/mcp/install?name=document-converter&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJnaXQraHR0cHM6Ly9naXRodWIuY29tL1phaGlkLUFiYmFzLUFsaS1CYWlnL2RvY3VtZW50LWNvbnZlcnRlciIsIi0td2l0aCIsIm1hcmtpdGRvd25bcGRmLGRvY3gscHB0eCx4bHN4LHhscyxvdXRsb29rLGF1ZGlvLXRyYW5zY3JpcHRpb24seW91dHViZS10cmFuc2NyaXB0aW9uXSIsImRvY3VtZW50LWNvbnZlcnRlci1tY3AiXX0%3D
Requires VS Code 1.102+ with built-in MCP support.
Do not paste
vscode://mcp/install?...anywhere. That link is broken in VS Code and creates servers likemy-mcp-server-*withspawn vscode://... ENOENT. Use the JSON below.
"command" starts with vscode:// (e.g. my-mcp-server-15e7e771).servers into your existing file):{
"servers": {
"document-converter": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter",
"--with",
"markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]",
"document-converter-mcp"
]
}
}
}
If you get uvx not found (ENOENT): run where uvx (Windows) or which uvx (macOS/Linux) and set "command" to the full path:
"command": "C:\\Users\\YOUR_USER\\.local\\bin\\uvx.exe"
git clone https://github.com/Zahid-Abbas-Ali-Baig/document-converter.gitdocument-converter.vscode/mcp.json automaticallyCtrl+Shift+P โ MCP: Add Server โ choose stdio, then enter:
| Field | Value |
|---|---|
| Command | uvx |
| Arg 1 | --from |
| Arg 2 | git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter |
| Arg 3 | --with |
| Arg 4 | markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription] |
| Arg 5 | document-converter-mcp |
Open Claude Desktop config:
%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/Library/Application Support/Claude/claude_desktop_config.jsonOn Windows Store Claude,
%APPDATA%\Claude\may not exist โ use thePackages\Claude_*\...path above.
Windows (Microsoft Store) โ one-time setup so uvx --from git+... can find Git (Claude passes a minimal PATH to MCP servers):
powershell -ExecutionPolicy Bypass -File scripts/setup-windows-uvx-git-shim.ps1
Or download and run that script from the repo. It creates %USERPROFILE%\.local\bin\git.cmd pointing at Git for Windows.
Add inside mcpServers (keep existing preferences at the root):
{
"mcpServers": {
"document-converter": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter",
"--with",
"markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]",
"document-converter-mcp"
]
}
}
}
If you get uvx not found (ENOENT): set "command" to the full path from where uvx, e.g. C:\\Users\\YOUR_USER\\.local\\bin\\uvx.exe.
Ask your AI assistant:
List the tools from document-converter MCP.
Or:
Preview markdown for a PDF on my machine at C:\path\to\file.pdf
You should see convert_to_markdown and preview_markdown being called.
| Tool | Description | Writes to disk |
|---|---|---|
convert_to_markdown | Converts a file or URL to Markdown and saves output (.md beside source, or youtube-{id}.md for YouTube URLs) | Yes |
preview_markdown | Returns Markdown in the chat response only | No |
Input: absolute or relative path to a file on your machine (or a supported URL for YouTube).
Output: Markdown text suitable for summarization, diffing, or committing to Git.
Natural-language prompts you can paste into Cursor, VS Code, or Claude Desktop after the MCP server is connected.
Prompt:
Use document-converter to convert C:\Reports\annual-report.pdf to markdown,
then give me a 5-bullet executive summary.
What happens: The agent calls convert_to_markdown, creates annual-report.md next to the PDF, and summarizes the result.
Prompt:
Preview markdown for ./contracts/vendor-agreement.docx without saving.
Tell me if there is a termination clause.
What happens: The agent calls preview_markdown, reads the content in chat, and answers your question โ no file is written.
Prompt:
Convert D:\data\sales-q1.xlsx to markdown and list the top 3 products by revenue.
What happens: Spreadsheet tables become Markdown the model can parse and rank.
Prompt:
Preview ./slides/product-launch.pptx as markdown and draft release notes
from the slide titles and bullet points.
Prompt:
Convert C:\Mail\customer-escalation.msg to markdown and extract action items.
Prompt:
Convert these to markdown and save beside each file:
- C:\Docs\spec-v2.pdf
- C:\Docs\api-reference.docx
- C:\Docs\metrics.xlsx
Then confirm the .md paths.
Prompt:
Preview markdown for ./recordings/standup-notes.mp3 and list decisions made.
Requires the audio-transcription extra (included in this project's dependencies).
Prompt (preview in chat):
Use preview_markdown on https://www.youtube.com/watch?v=EXAMPLE and summarize the main points.
Prompt (save to file):
Use convert_to_markdown on https://www.youtube.com/watch?v=EXAMPLE
What happens: MarkItDown fetches the watch page, extracts title/description/metadata, and appends captions via youtube-transcript-api when available. convert_to_markdown saves youtube-EXAMPLE.md in the server working directory.
Use https://www.youtube.com/watch?v=... format. Requires the youtube-transcription extra and an internet connection.
Illustrative snippet after conversion:
# Quarterly Results
Revenue increased 12% year over year driven by enterprise subscriptions.
## Highlights
- Net retention: 118%
- New logos: 240
- Gross margin: 74%
Quality depends on the source document layout and MarkItDown version.
Clone if you prefer a local virtual environment over uvx.
git clone https://github.com/Zahid-Abbas-Ali-Baig/document-converter.git
cd document-converter
python -m venv .venv
Windows (PowerShell):
.venv\Scripts\activate
pip install -r requirements.txt
macOS / Linux:
source .venv/bin/activate
pip install -r requirements.txt
Run the server directly (stdio โ used by MCP clients):
python server.py
All clients run the same underlying command (full JSON examples are in Quick install ๐ โ not repeated here):
| Part | Value |
|---|---|
| Command | uvx |
| Arg 1 | --from |
| Arg 2 | git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter |
| Arg 3 | --with |
| Arg 4 | markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription] |
| Arg 5 | document-converter-mcp |
| Client | File | JSON root key |
|---|---|---|
| Cursor | %USERPROFILE%\.cursor\mcp.json or .cursor/mcp.json | mcpServers |
| VS Code | User MCP config or .vscode/mcp.json | servers (+ "type": "stdio") |
| Claude Desktop | claude_desktop_config.json | mcpServers |
Copy-paste configs: Quick install ๐.
uvx)Clone and install โ see Local development ๐งช. Then point your MCP client at the venv Python:
Windows:
{
"mcpServers": {
"document-converter": {
"command": "REPO_PATH\\.venv\\Scripts\\python.exe",
"args": ["REPO_PATH\\server.py"]
}
}
}
macOS / Linux:
{
"mcpServers": {
"document-converter": {
"command": "REPO_PATH/.venv/bin/python",
"args": ["REPO_PATH/server.py"]
}
}
}
Listed on the official MCP Registry as io.github.Zahid-Abbas-Ali-Baig/document-converter (v1.0.0).
.mcpb bundle)markitdown[all] errorsIf you see errors about azure-ai-contentunderstanding or pre-releases, remove markitdown[all] from your config. Use:
markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]
spawn vscode://mcp/install?... ENOENTVS Code's install link wrote the URL as the command instead of uvx. Fix:
.vscode/mcp.json in this repo)my-mcp-server-* where "command" starts with vscode://.vscode/mcp.json from this repo, or the JSON in Install in VS Code ๐ปDo not use the README vscode://mcp/install?... link โ it is unreliable in VS Code.
Git executable not founduvx --from git+... needs Git on PATH. Microsoft Store Claude on Windows often spawns MCP servers with a minimal PATH that omits C:\Program Files\Git\cmd, even when Git works in a normal terminal.
Fix: run the one-time shim script from Install in Claude Desktop ๐ค (step 2). It places git.cmd next to uvx.exe in %USERPROFILE%\.local\bin.
Also ensure: Git for Windows and uv are installed. Pre-warm in PowerShell: uvx --from git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter --with markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription] document-converter-mcp (idle = normal for stdio).
Fallback: Local clone (no uvx) if you cannot use uvx.
Failed to acquire MessagePortThis comes from Cursor or VS Code, not this server:
[MCPService] Error creating client: Failed to acquire MessagePort ...
| Step | Action |
|---|---|
| 1 | Fully quit the editor, then reopen |
| 2 | Install uv for uvx installs |
| 3 | Test: uvx --from git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter --with markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription] document-converter-mcp (idle = normal for stdio) |
| 4 | Use Local clone (no uvx) if uvx fails |
| 5 | Settings โ MCP โ remove and re-add the server |
| 6 | Update Cursor/VS Code to the latest version |
Reliable fallback: follow Local development ๐งช and use the local clone MCP config.
Use the copy-paste JSON in Install in Cursor ๐ฑ๏ธ instead of the install badge.
Reload MCP or restart the editor. Confirm the server is enabled (not red/disabled).
MIT License โ see LICENSE.
Copyright (c) 2026 Zahid Abbas Ali Baig
Be the first to review this server!
by Modelcontextprotocol ยท Developer Tools
Read, search, and manipulate Git repositories programmatically
by Modelcontextprotocol ยท Developer Tools
Web content fetching and conversion for efficient LLM usage
by Toleno ยท Developer Tools
Toleno Network MCP Server โ Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace ยท Developer Tools
Create, build, and publish Python MCP servers to PyPI โ conversationally.
by Microsoft ยท Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
by mcp-marketplace ยท Finance
Free stock data and market news for any MCP-compatible AI assistant.