Markitdown Mcp Npx

开发 JavaScript

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

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

🔧 可用选项

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

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

🔍 工作原理

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

🧪 使用 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 核心功能相关的问题，请参考原始仓库。

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

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

🙏 致谢

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

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

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

0 条评论
分类：开发

Markitdown Mcp Npx