Markitdown MCP Npx

🚀 MarkItDown-MCP-NPX

NPX 包装器，用于运行微软的 MarkItDown MCP 服务器，无需 Docker！ 本软件包为微软的 markitdown-mcp 提供了一个与 NPX 兼容的包装器，让你无需依赖 Docker 即可运行 MarkItDown MCP 服务器。

🚀 快速开始

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

# 基本标准输入输出模式（适用于 Claude Desktop）
npx -y markitdown-mcp-npx

# 用于测试的 HTTP 模式
npx -y markitdown-mcp-npx --http --host 127.0.0.1 --port 3001

# 显示帮助信息
npx -y markitdown-mcp-npx --help

其他安装方法

本地安装

# 全局安装
npm install -g markitdown-mcp-npx

# 直接运行
markitdown-mcp-npx

本地开发

# 克隆此仓库
git clone https://github.com/xkiranj/markitdown-mcp-npx.git
cd markitdown-mcp-npx

# 本地运行
npm start

✨ 主要特性

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

📋 前提条件

必需条件

• Node.js 16+：NPX 执行所需
• Python 3.10+：MarkItDown 功能所需
• 互联网连接：用于初始包安装

可选条件（用于增强功能）

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

💡 注意：MarkItDown 在大多数文件类型（PDF、Word、Excel、基本图像）处理中无需可选依赖项即可完美工作。仅在处理音频文件和高级图像元数据时需要这些依赖项。

Windows 用户：有关可选依赖项的轻松安装方法，请参阅 WINDOWS_SETUP.md。

💻 使用示例

基本标准输入输出模式（默认）

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

一次性设置验证

# 测试安装并显示帮助信息
npx -y markitdown-mcp-npx --help

📚 详细文档

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 版本的比较

🔧 可用选项

用法: markitdown-mcp-npx [选项]

选项:
  --http           使用可流式传输的 HTTP 和 SSE 传输运行（默认：标准输入输出）
  --sse            --http 的别名（已弃用）
  --host HOST      绑定的主机（默认：127.0.0.1）
  --port PORT      监听的端口（默认：3001）
  --help           显示帮助信息

🔍 工作原理

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

🧪 使用 MCP 检查器进行测试

你可以使用 MCP 检查器测试服务器：

# 启动检查器
npx @modelcontextprotocol/inspector

# 对于标准输入输出模式：
# - 传输方式：标准输入输出
# - 命令：npx
# - 参数：-y, markitdown-mcp-npx

# 对于 HTTP 模式：
# - 启动服务器：npx -y markitdown-mcp-npx --http
# - 传输方式：可流式传输的 HTTP
# - URL：http://127.0.0.1:3001/mcp

🔧 预期工具行为

• ✓ 单一工具：MarkItDown MCP 仅提供一个名为 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”是正常现象！

🐛 故障排除

服务器启动时挂起

服务器在启动时似乎挂起或超时

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

未找到 Python

错误: 需要 Python 3.10+ 但未找到

解决方案：安装 Python 3.10+ 并确保其已添加到系统路径中。

权限错误

错误: 无法创建虚拟环境

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

安装失败

错误: 无法安装 markitdown-mcp

解决方案：检查互联网连接和代理设置。

端口已被占用

错误: 端口 3001 已被占用

解决方案：使用 --port <数字> 指定不同的端口。

NPX 缓存问题

错误: 未找到包或包已过期

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

FFmpeg 警告

运行时警告: 未找到 ffmpeg 或 avconv - 默认使用 ffmpeg，但可能无法正常工作

此警告无害！ 这意味着：

• ✅ MarkItDown 正常工作
• ✅ 所有文件类型均可处理（PDF、Word、Excel、图像）
• ⚠️ 音频文件（.mp3、.wav）处理将受限

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

📂 文件结构

markitdown-mcp-npx/
├── package.json              # NPM 包配置
├── index.js                  # 主入口点
├── bin/
│   └── markitdown-mcp-npx.js # Node.js 可执行脚本
├── README.md                 # 本文件
├── WINDOWS_SETUP.md          # Windows 安装指南
├── test.js                   # 测试套件
└── LICENSE                   # MIT 许可证

🔐 安全注意事项

• 服务器以执行用户的相同权限运行。
• HTTP/SSE 模式未提供身份验证。
• 除非特别需要，否则在 HTTP 模式下应绑定到 localhost。
• 虚拟环境为 Python 依赖项提供隔离。
• NPX 确保你始终使用最新发布的版本。

🆚 与 Docker 版本对比

NPX 版本的优势

• ✅ 无需安装 Docker
• ✅ 使用 NPX 零配置
• ✅ 直接访问文件系统（无需挂载卷）
• ✅ 启动更快（无容器开销）
• ✅ 更易于调试和故障排除
• ✅ 使用 NPX 始终保持最新版本

Docker 版本的优势

• ✅ 完全隔离
• ✅ 跨系统环境一致
• ✅ 主机无需安装 Python

📈 版本更新

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

# 清除缓存并运行最新版本
npx -y markitdown-mcp-npx

# 检查当前版本
npx -y markitdown-mcp-npx --help

📦 包信息

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

🤝 贡献

这是微软 MarkItDown MCP 服务器的非官方包装器。如果遇到 MarkItDown 核心功能相关的问题，请参考 原始仓库。

如果遇到此包装器特有的问题：

1. 查看故障排除部分。
2. 验证你的 Python 和 Node.js 安装。
3. 使用 MCP 检查器进行测试。
4. 在 GitHub 上 提交问题。

🙏 致谢

• 微软 AutoGen 团队：创建了原始的 MarkItDown 和 MCP 服务器。
• 模型上下文协议：提供了 MCP 规范。
• Claude Desktop：实现了 MCP 集成。
• NPM 社区：提供了出色的 NPX 工具。

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

这是 MarkItDown MCP 的非官方包装器。如需官方 Docker 版本，请访问 原始仓库。