🚀 MarkItDown-MCP-NPX

MarkItDown-MCP-NPX 是微软 MarkItDown MCP 服务器的 NPX 封装器，无需使用 Docker！该项目允许你在不依赖 Docker 的情况下运行 MarkItDown MCP 服务器。

🚀 快速开始

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

# 基本 STDIO 模式（适用于 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 以轻松安装可选依赖项。

💻 使用示例

基本 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

一次性设置验证

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

📚 详细文档

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

🔧 可用选项

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

选项:
  --http           使用可流式传输的 HTTP 和 SSE 传输运行（默认: STDIO）
  --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

# 对于 STDIO 模式:
# - 传输方式: STDIO
# - 命令: 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 个工具可用”是正常现象！

🐛 故障排除

服务器启动时挂起

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

解决方案：确保使用 -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 服务器
• Model Context Protocol：提供了 MCP 规范
• Claude Desktop：实现了 MCP 集成
• NPM 社区：提供了出色的 NPX 工具

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

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