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!)

# 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

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)

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

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:

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

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.

Name		Name	Last commit message	Last commit date
.github		.github
bin		bin
.gitignore		.gitignore
.npmignore		.npmignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
WINDOWS_SETUP.md		WINDOWS_SETUP.md
index.js		index.js
package.json		package.json
test.js		test.js

Latest commit

History

Folders and files

Repository files navigation