Optional integration for enhanced audio file processing and transcription capabilities (.mp3, .wav files) in the MarkItDown conversion process
Core functionality of the server is converting various file formats to Markdown, providing a universal converter that handles multiple document, image, audio, web, archive, and data file types
MarkItDown-MCP-NPX
NPX wrapper for Microsoft's MarkItDown MCP server - No Docker Required!
This package provides an NPX-compatible wrapper for Microsoft's markitdown-mcp, allowing you to run the MarkItDown MCP server without Docker dependencies.
✨ Features
- 🚀 No Docker Required: Run directly with NPX - no installation needed
- 🔧 Automatic Setup: Handles Python environment and dependencies automatically
- 🔄 Full Compatibility: Works exactly like the original Docker version
- 💻 Cross-Platform: Works on Windows, macOS, and Linux
- ⚡ Fast: Reuses virtual environment after first setup
- 📦 Zero Config: Just run
npx -y markitdown-mcp-npx
and you're ready!
📋 Prerequisites
Required
- Node.js 16+: Required for NPX execution
- Python 3.10+: Required for MarkItDown functionality
- Internet Connection: For initial package installation
Optional (for enhanced functionality)
- FFmpeg: For audio file processing and transcription (.mp3, .wav files)
- ExifTool: For advanced image metadata extraction
💡 Note: MarkItDown works perfectly for most file types (PDF, Word, Excel, basic images) without the optional dependencies. They're only needed for audio files and advanced image metadata.
Windows users: See WINDOWS_SETUP.md for easy installation of optional dependencies.
🚀 Quick Start
Using NPX (Recommended - No Installation Required!)
Alternative Installation Methods
Local Installation
Local Development
🔧 Configuration for Claude Desktop
Claude Desktop Configuration (Recommended)
NPX Version (Recommended):
With HTTP transport:
Global Installation:
🔑 Critical: The
-y
flag is required for NPX in Claude Desktop to prevent installation prompts that would cause the server to hang.
Comparison with Docker Version
Feature | Docker Version | NPX Version |
---|---|---|
Setup | Requires Docker | Just NPX (comes with Node.js) |
Command | docker run ... | npx -y markitdown-mcp-npx |
Dependencies | Isolated in container | Managed in virtual environment |
Performance | Container overhead | Direct execution |
File Access | Requires volume mounts | Direct file system access |
Installation | Docker pull required | Zero installation with NPX |
📖 Usage Examples
Basic STDIO Mode (Default)
HTTP/SSE Mode
With Custom Host/Port
One-time Setup Verification
🛠️ Available Options
🔍 How It Works
- NPX Magic: NPX automatically downloads and runs the latest version
- Auto-confirmation: The
-y
flag skips installation prompts for seamless startup - Environment Detection: Automatically detects Python 3.10+ installation
- Virtual Environment: Creates isolated Python environment in temp directory
- Package Installation: Installs
markitdown-mcp
and dependencies - Process Management: Spawns and manages the Python MCP server process
- Signal Handling: Properly handles termination signals
- Caching: Reuses the virtual environment for faster subsequent runs
🧪 Testing with MCP Inspector
You can test the server using the MCP Inspector:
🔧 Expected Tool Behavior
✓ Single Tool: MarkItDown MCP provides exactly 1 tool called convert_to_markdown
✓ Universal Converter: This one tool handles all file types:
- 📄 Documents: PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx)
- 🖼️ Images: JPG, PNG, GIF, etc. (with OCR support)
- 🎧 Audio: MP3, WAV (with transcription if FFmpeg installed)
- 🌐 Web: HTTP/HTTPS URLs
- 🗃️ Archives: ZIP files
- 📊 Data: CSV, JSON, XML
✓ URI Parameter: Accepts http:
, https:
, file:
, or data:
URIs
💡 Note: Seeing "1 tools available" in Claude Desktop is correct behavior!
🐛 Troubleshooting
Server Hangs on Startup
Solution: Ensure you're using the -y
flag: npx -y markitdown-mcp-npx
Cause: Without -y
, NPX prompts for installation confirmation, which hangs in non-interactive environments like Claude Desktop.
Python Not Found
Solution: Install Python 3.10+ and ensure it's in your PATH
Permission Errors
Solution: Check write permissions to your temp directory
Installation Failures
Solution: Check internet connectivity and proxy settings
Port Already in Use
Solution: Use a different port with --port <number>
NPX Cache Issues
Solution: Clear NPX cache with npx clear-npx-cache
or use npx -y markitdown-mcp-npx
FFmpeg Warning
This warning is harmless! It means:
- ✅ MarkItDown is working correctly
- ✅ All file types work (PDF, Word, Excel, images)
- ⚠️ Audio files (.mp3, .wav) processing will be limited
To resolve: Install FFmpeg (see WINDOWS_SETUP.md for Windows)
📂 File Structure
🔐 Security Considerations
- The server runs with the same privileges as the user executing it
- No authentication is provided for HTTP/SSE modes
- For HTTP mode, bind to
localhost
unless specifically needed otherwise - Virtual environments provide isolation for Python dependencies
- NPX ensures you always get the latest published version
🆚 vs. Docker Version
Advantages of NPX Version:
- ✅ No Docker installation required
- ✅ Zero configuration with NPX
- ✅ Direct file system access (no volume mounts)
- ✅ Faster startup (no container overhead)
- ✅ Easier to debug and troubleshoot
- ✅ Always up-to-date with NPX
Advantages of Docker Version:
- ✅ Complete isolation
- ✅ Consistent environment across systems
- ✅ No Python installation required on host
📈 Version Updates
The NPX version automatically uses the latest published version. To check for updates or force a fresh download:
📦 Package Information
- Package: markitdown-mcp-npx
- Repository: GitHub
- License: MIT
- Node.js: >=16.0.0
- Python: >=3.10
🤝 Contributing
This is an unofficial wrapper for Microsoft's MarkItDown MCP server. For issues with the core MarkItDown functionality, please refer to the original repository.
For issues specific to this wrapper:
- Check the troubleshooting section
- Verify your Python and Node.js installations
- Test with the MCP Inspector
- Open an issue on GitHub
🙏 Acknowledgments
- Microsoft AutoGen Team: For creating the original MarkItDown and MCP server
- Model Context Protocol: For the MCP specification
- Claude Desktop: For MCP integration
- NPM Community: For the fantastic NPX tool
✨ Ready to use? Just run: npx -y markitdown-mcp-npx
This is an unofficial wrapper for MarkItDown MCP. For the official Docker version, visit the original repository.
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Converts various file types (documents, images, audio, web content) to markdown format without requiring Docker, supporting PDF, Word, Excel, PowerPoint, images, audio files, web URLs, and more.
- ✨ Features
- 📋 Prerequisites
- 🚀 Quick Start
- 🔧 Configuration for Claude Desktop
- 📖 Usage Examples
- 🛠️ Available Options
- 🔍 How It Works
- 🧪 Testing with MCP Inspector
- 🔧 Expected Tool Behavior
- 🐛 Troubleshooting
- 📂 File Structure
- 🔐 Security Considerations
- 🆚 vs. Docker Version
- 📈 Version Updates
- 📦 Package Information
- 🤝 Contributing
- 🙏 Acknowledgments
Related MCP Servers
- AsecurityAlicenseAqualityConverts various file types and web content to Markdown format. It provides a set of tools to transform PDFs, images, audio files, web pages, and more into easily readable and shareable Markdown text.Last updated -1021,611TypeScriptMIT License
- AsecurityAlicenseAqualityConverts various file formats to Markdown using the MarkItDown utility and can be integrated with MCP clients for seamless document processing and conversion.Last updated -26PythonMIT License
- AsecurityAlicenseAqualityA document conversion server that transforms various file formats (PDFs, documents, images, audio, web content) to Markdown with improved multilingual and UTF-8 support.Last updated -104TypeScriptMIT License
- AsecurityFlicenseAqualityA server that converts various file formats (PDF, images, Office documents, etc.) to Markdown descriptions using Cloudflare AI services.Last updated -1233JavaScript