MarkItDown-MCP-NPX

MarkItDown-MCP-NPX

Microsoft MarkItDown MCP 服务的 NPX 封装器——无需 Docker！

此软件包为 Microsoft 的 markitdown-mcp 提供兼容 NPX 的封装器，让你无需 Docker 依赖即可运行 MarkItDown MCP 服务。

✨ 功能

• 🚀 无需 Docker：直接使用 NPX 运行，无需安装
• 🔧 自动设置：自动处理 Python 环境和依赖项
• 🔄 完全兼容：运行方式与原始 Docker 版本完全相同
• 💻 跨平台：支持 Windows、macOS 和 Linux
• ⚡ 快速：首次设置后可重复使用虚拟环境
• 📦 零配置：只需运行 npx -y markitdown-mcp-npx 即可开始使用！

📋 先决条件

必需

• Node.js 16+：运行 NPX 所必需
• Python 3.10+：MarkItDown 功能所必需
• 互联网连接：用于首次安装软件包

可选（用于增强功能）

• FFmpeg：用于音频文件处理和转录（.mp3、.wav 文件）
• ExifTool：用于提取高级图像元数据

💡 注意：对于大多数文件类型（PDF、Word、Excel、基本图像），即使没有可选依赖项，MarkItDown 也能正常工作。只有处理音频文件和提取高级图像元数据时才需要这些依赖项。

Windows 用户：请参阅 WINDOWS_SETUP.md，了解如何轻松安装可选依赖项。

🚀 快速开始

使用 NPX（推荐——无需安装！）

# 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

🔧 Claude Desktop 配置

Claude Desktop 配置（推荐）

NPX 版本（推荐）：

{
  "mcpServers": {
    "markitdown": {
      "command": "npx",
      "args": [
        "-y",
        "markitdown-mcp-npx"
      ]
    }
  }
}

使用 HTTP 传输：

{
  "mcpServers": {
    "markitdown": {
      "command": "npx",
      "args": [
        "-y",
        "markitdown-mcp-npx",
        "--http",
        "--host",
        "127.0.0.1",
        "--port",
        "3001"
      ]
    }
  }
}

全局安装：

{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp-npx",
      "args": []
    }
  }
}

🔑 重要提示：在 Claude Desktop 中使用 NPX 时，必须加上 -y 标志，以跳过安装提示，避免服务挂起。

与 Docker 版本的比较

功能	Docker 版本	NPX 版本
设置	需要 Docker	只需 NPX（随 Node.js 一同提供）
命令	docker run ...	npx -y markitdown-mcp-npx
依赖项	隔离在容器中	在虚拟环境中管理
性能	容器开销	直接执行
文件访问	需要挂载卷	直接访问文件系统
安装	需要拉取 Docker 镜像	使用 NPX，无需安装

📖 使用示例

基本 STDIO 模式（默认）

npx -y markitdown-mcp-npx

HTTP/SSE 模式

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

🔍 工作原理

1. NPX 自动运行：NPX 会自动下载并运行最新版本
2. 自动确认：-y 标志会跳过安装提示，确保顺畅启动
3. 环境检测：自动检测 Python 3.10+ 安装
4. 虚拟环境：在临时目录中创建隔离的 Python 环境
5. 安装软件包：安装 markitdown-mcp 及其依赖项
6. 进程管理：启动并管理 Python MCP 服务进程
7. 信号处理：正确处理终止信号
8. 缓存：重复使用虚拟环境，加快后续运行速度

🧪 使用 MCP Inspector 测试

你可以使用 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

🔧 预期工具行为

✓ 单一工具：MarkItDown MCP 恰好提供 1 个工具，名为 convert_to_markdown
✓ 通用转换器：这个工具可处理所有文件类型：

• 📄 文档：PDF、Word（.docx）、Excel（.xlsx）、PowerPoint（.pptx）
• 🖼️ 图像：JPG、PNG、GIF 等（支持 OCR）
• 🎧 音频：MP3、WAV（安装 FFmpeg 后可进行转录）
• 🌐 网页：HTTP/HTTPS URL
• 🗃️ 压缩包：ZIP 文件
• 📊 数据：CSV、JSON、XML

✓ URI 参数：接受 http:、https:、file: 或 data: URI

💡 注意：在 Claude Desktop 中看到“1 tools available”是正常行为！

🐛 故障排除

服务在启动时挂起

Server appears to hang or timeout on startup

解决方案：确保使用 -y 标志：npx -y markitdown-mcp-npx
原因：如果不使用 -y，NPX 会提示确认安装，在 Claude Desktop 这类非交互环境中会导致挂起。

找不到 Python

Error: Python 3.10+ is required but not found

解决方案：安装 Python 3.10+，并确保它位于 PATH 中

权限错误

Error: Failed to create virtual environment

解决方案：检查临时目录的写入权限

安装失败

Error: Failed to install markitdown-mcp

解决方案：检查网络连接和代理设置

端口已被占用

Error: Port 3001 already in use

解决方案：使用 --port <number> 指定其他端口

NPX 缓存问题

Error: Package not found or outdated

解决方案：使用 npx clear-npx-cache 清除 NPX 缓存，或使用 npx -y markitdown-mcp-npx

FFmpeg 警告

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

此警告无害！ 这意味着：

• ✅ MarkItDown 正常运行
• ✅ 所有文件类型均可处理（PDF、Word、Excel、图像）
• ⚠️ 音频文件（.mp3、.wav）的处理功能会受限

解决方法：安装 FFmpeg（Windows 用户请参阅 WINDOWS_SETUP.md）

📂 文件结构

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

🔐 安全注意事项

• 服务以运行它的用户的相同权限运行
• HTTP/SSE 模式不提供身份验证
• 对于 HTTP 模式，除非有特别需要，否则请绑定到 localhost
• 虚拟环境可隔离 Python 依赖项
• NPX 可确保你始终获取最新发布版本

🆚 与 Docker 版本对比

NPX 版本的优点：

• ✅ 无需安装 Docker
• ✅ 使用 NPX 无需任何配置
• ✅ 可直接访问文件系统（无需挂载卷）
• ✅ 启动更快（无容器开销）
• ✅ 更易于调试和排查问题
• ✅ 通过 NPX 始终保持最新

Docker 版本的优点：

• ✅ 完全隔离
• ✅ 不同系统间环境一致
• ✅ 主机上无需安装 Python

📈 版本更新

NPX 版本会自动使用最新发布版本。若要检查更新或强制重新下载：

# Clear cache and run latest version
npx -y markitdown-mcp-npx

# Check current version
npx -y markitdown-mcp-npx --help

📦 软件包信息

• 软件包：markitdown-mcp-npx
• 代码仓库：GitHub
• 许可证：MIT
• Node.js：>=16.0.0
• Python：>=3.10

🤝 贡献

这是 Microsoft MarkItDown MCP 服务的非官方封装。若遇到 MarkItDown 核心功能相关问题，请参阅原始代码仓库。

若遇到此封装特有的问题：

1. 查看故障排除部分
2. 确认已正确安装 Python 和 Node.js
3. 使用 MCP Inspector 进行测试
4. 在 GitHub 上提交问题

🙏 致谢

• Microsoft AutoGen Team：创建了原始的 MarkItDown 和 MCP 服务
• Model Context Protocol：提供 MCP 规范
• Claude Desktop：提供 MCP 集成
• NPM 社区：提供出色的 NPX 工具

---

✨ 准备好使用了吗？只需运行：npx -y markitdown-mcp-npx

这是 MarkItDown MCP 的非官方封装。如需使用官方 Docker 版本，请访问原始代码仓库。