markitdown-mcp-npx
Advanced tools
NPX wrapper for Microsoft's MarkItDown MCP server - run without Docker. Provides the same file conversion capabilities (PDF, Word, Excel, images, etc.) as the original Docker version but with easier setup and direct file system access.
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.
npx -y markitdown-mcp-npx and you're ready!💡 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.
# Basic STDIO mode (for Claude Desktop)
npx -y markitdown-mcp-npx
# HTTP mode for testing
npx -y markitdown-mcp-npx --http --host 127.0.0.1 --port 3001
# Show help
npx -y markitdown-mcp-npx --help
# Install globally
npm install -g markitdown-mcp-npx
# Then run directly
markitdown-mcp-npx
# Clone this repository
git clone https://github.com/xkiranj/markitdown-mcp-npx.git
cd markitdown-mcp-npx
# Run locally
npm start
NPX Version (Recommended):
{
"mcpServers": {
"markitdown": {
"command": "npx",
"args": [
"-y",
"markitdown-mcp-npx"
]
}
}
}
With HTTP transport:
{
"mcpServers": {
"markitdown": {
"command": "npx",
"args": [
"-y",
"markitdown-mcp-npx",
"--http",
"--host",
"127.0.0.1",
"--port",
"3001"
]
}
}
}
Global Installation:
{
"mcpServers": {
"markitdown": {
"command": "markitdown-mcp-npx",
"args": []
}
}
}
🔑 Critical: The
-yflag is required for NPX in Claude Desktop to prevent installation prompts that would cause the server to hang.
| 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 |
npx -y markitdown-mcp-npx
npx -y markitdown-mcp-npx --http --host 127.0.0.1 --port 3001
npx -y markitdown-mcp-npx --http --host 0.0.0.0 --port 8080
# Test installation and show help
npx -y markitdown-mcp-npx --help
Usage: markitdown-mcp-npx [options]
Options:
--http Run with Streamable HTTP and SSE transport (default: STDIO)
--sse Alias for --http (deprecated)
--host HOST Host to bind to (default: 127.0.0.1)
--port PORT Port to listen on (default: 3001)
--help Show help message
-y flag skips installation prompts for seamless startupmarkitdown-mcp and dependenciesYou can test the server using the MCP Inspector:
# Start the inspector
npx @modelcontextprotocol/inspector
# For STDIO mode:
# - Transport: STDIO
# - Command: npx
# - Args: -y, markitdown-mcp-npx
# For HTTP mode:
# - Start server: npx -y markitdown-mcp-npx --http
# - Transport: Streamable HTTP
# - URL: http://127.0.0.1:3001/mcp
✓ Single Tool: MarkItDown MCP provides exactly 1 tool called convert_to_markdown
✓ Universal Converter: This one tool handles all file types:
✓ URI Parameter: Accepts http:, https:, file:, or data: URIs
💡 Note: Seeing "1 tools available" in Claude Desktop is correct behavior!
Server appears to hang or timeout 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.
Error: Python 3.10+ is required but not found
Solution: Install Python 3.10+ and ensure it's in your PATH
Error: Failed to create virtual environment
Solution: Check write permissions to your temp directory
Error: Failed to install markitdown-mcp
Solution: Check internet connectivity and proxy settings
Error: Port 3001 already in use
Solution: Use a different port with --port <number>
Error: Package not found or outdated
Solution: Clear NPX cache with npx clear-npx-cache or use npx -y markitdown-mcp-npx
RuntimeWarning: Couldn't find ffmpeg or avconv - defaulting to ffmpeg, but may not work
This warning is harmless! It means:
To resolve: Install FFmpeg (see WINDOWS_SETUP.md for Windows)
markitdown-mcp-npx/
├── package.json # NPM package configuration
├── index.js # Main entry point
├── bin/
│ └── markitdown-mcp-npx.js # Node.js executable script
├── README.md # This file
├── WINDOWS_SETUP.md # Windows setup guide
├── test.js # Test suite
└── LICENSE # MIT License
localhost unless specifically needed otherwiseThe NPX version automatically uses the latest published version. To check for updates or force a fresh download:
# Clear cache and run latest version
npx -y markitdown-mcp-npx
# Check current version
npx -y markitdown-mcp-npx --help
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:
✨ 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.
FAQs
NPX wrapper for Microsoft's MarkItDown MCP server - run without Docker. Provides the same file conversion capabilities (PDF, Word, Excel, images, etc.) as the original Docker version but with easier setup and direct file system access.
The npm package markitdown-mcp-npx receives a total of 70 weekly downloads. As such, markitdown-mcp-npx popularity was classified as not popular.
We found that markitdown-mcp-npx demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.
Security News
AGENTS.md is a fast-growing open format giving AI coding agents a shared, predictable way to understand project setup, style, and workflows.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.