标记ダウン-MCP-NPX

Name: 标记ダウン-MCP-NPX
Author: xkiranj

作者：xkiranj10 星标更新：2025-06-12

安装使用来源：spider==github.com

项目介绍

MarkItDown-MCP-NPX

Microsoft 的 MarkItDown MCP 服务器的 NPX 包装器 - 不需要 Docker！

此包提供了一个与 NPX 兼容的包装器，用于 Microsoft 的 markitdown-mcp，允许您无需 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：用于高级图像元数据提取

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

Windows 用户：参见 WINDOWS_SETUP.md 以轻松安装可选依赖。

🚀 快速开始

使用 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

🔧 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

一次性设置验证

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

🛠️ 可用选项

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

选项：
  --http           使用流式 HTTP 和 SSE 传输（默认：STDIO）
  --sse            --http 的别名（已弃用）
  --host 主机      绑定到的主机（默认：127.0.0.1）
  --port 端口      监听的端口（默认：3001）
  --help           显示帮助信息

🔍 工作原理

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

🧪 使用 MCP Inspector 测试

您可以使用 MCP Inspector 来测试服务器：

# 启动检查器
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+ 并确保它在您的 PATH 中

权限错误

错误：无法创建虚拟环境

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

安装失败

错误：无法安装 markitdown-mcp

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

端口已被占用

错误：端口 3001 已被占用

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

NPX 缓存问题

错误：找不到或过时的包

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

FFmpeg 警告

运行时警告：找不到 ffmpeg 或 avconv - 默认使用 ffmpeg，但可能不起作用

此警告无害！ 它意味着：

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

解决方法：安装 FFmpeg（参见 WINDOWS_SETUP.md 以了解 Windows 安装）

📂 文件结构

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

🤝 贡献

这是一个 Microsoft 的 MarkItDown MCP 服务器的非官方包装器。对于核心 MarkItDown 功能的问题，请参考原始仓库。

对于此包装器特有的问题：

查看故障排除部分
验证您的 Python 和 Node.js 安装
使用 MCP Inspector 测试
在 GitHub 上打开一个问题

🙏 致谢

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

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

这是一个 MarkItDown MCP 的非官方包装器。要获取官方 Docker 版本，请访问原始仓库。