Skip to main content
Glama

MarkItDown MCP

by xkiranj
npmGitHub
JavaScript
98
1
  • Apple
  • Linux
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

# 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

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

FeatureDocker VersionNPX Version
SetupRequires DockerJust NPX (comes with Node.js)
Commanddocker run ...npx -y markitdown-mcp-npx
DependenciesIsolated in containerManaged in virtual environment
PerformanceContainer overheadDirect execution
File AccessRequires volume mountsDirect file system access
InstallationDocker pull requiredZero 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

  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 isolated Python environment in 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 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

🤝 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.

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

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.

  1. ✨ Features
    1. 📋 Prerequisites
      1. Required
      2. Optional (for enhanced functionality)
    2. 🚀 Quick Start
      1. Using NPX (Recommended - No Installation Required!)
      2. Alternative Installation Methods
    3. 🔧 Configuration for Claude Desktop
      1. Claude Desktop Configuration (Recommended)
      2. Comparison with Docker Version
    4. 📖 Usage Examples
      1. Basic STDIO Mode (Default)
      2. HTTP/SSE Mode
      3. With Custom Host/Port
      4. One-time Setup Verification
    5. 🛠️ Available Options
      1. 🔍 How It Works
        1. 🧪 Testing with MCP Inspector
          1. 🔧 Expected Tool Behavior
            1. 🐛 Troubleshooting
              1. Server Hangs on Startup
              2. Python Not Found
              3. Permission Errors
              4. Installation Failures
              5. Port Already in Use
              6. NPX Cache Issues
              7. FFmpeg Warning
            2. 📂 File Structure
              1. 🔐 Security Considerations
                1. 🆚 vs. Docker Version
                  1. Advantages of NPX Version:
                  2. Advantages of Docker Version:
                2. 📈 Version Updates
                  1. 📦 Package Information
                    1. 🤝 Contributing
                      1. 🙏 Acknowledgments

                        Related MCP Servers

                        • Markdownify MCP Server

                          zcaceres
                          A
                          security
                          A
                          license
                          A
                          quality
                          Converts 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 -
                          10
                          2
                          1,611
                          TypeScript
                          MIT License
                          • Apple

                        • MarkItDown MCP Server

                          KorigamiK
                          A
                          security
                          A
                          license
                          A
                          quality
                          Converts various file formats to Markdown using the MarkItDown utility and can be integrated with MCP clients for seamless document processing and conversion.
                          Last updated -
                          26
                          Python
                          MIT License

                        • Markdownify MCP Server - UTF-8 Enhanced

                          JDJR2024
                          A
                          security
                          A
                          license
                          A
                          quality
                          A 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 -
                          10
                          4
                          TypeScript
                          MIT License
                          • Linux
                          • Apple

                        • MCP Markdown Conversion Server

                          FradSer
                          A
                          security
                          F
                          license
                          A
                          quality
                          A server that converts various file formats (PDF, images, Office documents, etc.) to Markdown descriptions using Cloudflare AI services.
                          Last updated -
                          1
                          2
                          33
                          JavaScript
                          • Linux
                          • Apple

                        View all related MCP servers

                        New MCP Servers

                        MCP directory API

                        We provide all the information about MCP servers via our MCP API.

                        curl -X GET 'https://glama.ai/api/mcp/v1/servers/xkiranj/markitdown-mcp-npx'

                        If you have feedback or need assistance with the MCP directory API, please join our Discord server