Markitdown MCP Npx

🚀 MarkItDown-MCP-NPX

An NPX wrapper for Microsoft's MarkItDown MCP server, eliminating the need for Docker!

This package offers an NPX-compatible wrapper for Microsoft's markitdown-mcp, enabling you to run the MarkItDown MCP server without Docker dependencies.

✨ Features

• 🚀 No Docker Required: Run directly with NPX, no installation needed.
• 🔧 Automatic Setup: Automatically handles the Python environment and dependencies.
• 🔄 Full Compatibility: Functions exactly like the original Docker version.
• 💻 Cross-Platform: Works on Windows, macOS, and Linux.
• ⚡ Fast: Reuses the virtual environment after the first setup.
• 📦 Zero Config: Just run npx -y markitdown-mcp-npx and you're good to go!

📋 Prerequisites

Required

• Node.js 16+: Necessary 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 well 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!)

# 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

Alternative Installation Methods

Local Installation

# Install globally
npm install -g markitdown-mcp-npx

# Then run directly
markitdown-mcp-npx

Local Development

# Clone this repository
git clone https://github.com/xkiranj/markitdown-mcp-npx.git
cd markitdown-mcp-npx

# Run locally
npm start

🔧 Configuration for Claude Desktop

Claude Desktop Configuration (Recommended)

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 -y flag is required for NPX in Claude Desktop to prevent installation prompts that would cause the server to hang.

Comparison with Docker Version

💻 Usage Examples

Basic STDIO Mode (Default)

npx -y markitdown-mcp-npx

HTTP/SSE Mode

npx -y markitdown-mcp-npx --http --host 127.0.0.1 --port 3001

With Custom Host/Port

npx -y markitdown-mcp-npx --http --host 0.0.0.0 --port 8080

One-time Setup Verification

# Test installation and show help
npx -y markitdown-mcp-npx --help

🛠️ Available Options

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

🔍 How It Works

1. NPX Magic: NPX automatically downloads and runs the latest version.
2. Auto-confirmation: The -y flag skips installation prompts for seamless startup.
3. Environment Detection: Automatically detects Python 3.10+ installation.
4. Virtual Environment: Creates an isolated Python environment in the temp directory.
5. Package Installation: Installs markitdown-mcp and dependencies.
6. Process Management: Spawns and manages the Python MCP server process.
7. Signal Handling: Properly handles termination signals.
8. Caching: Reuses the virtual environment for faster subsequent runs.

🧪 Testing with MCP Inspector

You 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

🔧 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

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.

Python Not Found

Error: Python 3.10+ is required but not found

Solution: Install Python 3.10+ and ensure it's in your PATH.

Permission Errors

Error: Failed to create virtual environment

Solution: Check write permissions to your temp directory.

Installation Failures

Error: Failed to install markitdown-mcp

Solution: Check internet connectivity and proxy settings.

Port Already in Use

Error: Port 3001 already in use

Solution: Use a different port with --port <number>.

NPX Cache Issues

Error: Package not found or outdated

Solution: Clear NPX cache with npx clear-npx-cache or use npx -y markitdown-mcp-npx.

FFmpeg Warning

RuntimeWarning: Couldn't find ffmpeg or avconv - defaulting to ffmpeg, but may not work

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

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

🔐 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 the host.

📈 Version Updates

The 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

📦 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:

1. Check the troubleshooting section.
2. Verify your Python and Node.js installations.
3. Test with the MCP Inspector.
4. 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.