Markitdown MCP Npx

MarkItDown MCP NPX

](https://www.npmjs.com/package/markitdown-mcp-npx) ](https://www.npmjs.com/package/markitdown-mcp-npx) 

微软MarkItDown MCP服务器的NPX包装器-无需Docker！

此软件包为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功能所需
• Internet连接：用于初始软件包安装

可选（用于增强功能）

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

💡 备注：MarkItDown适用于大多数文件类型（PDF、Word、Excel、基本图像），没有可选的依赖关系。它们只需要用于音频文件和高级图像元数据。

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桌面配置

Claude桌面配置（推荐）

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": []
    }
  }
}

🔑 关键的：The -y 旗是 必需的 Claude Desktop中的NPX可以防止安装提示导致服务器挂起。

与Docker版本的比较

📖 使用示例

基本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. 自动确认：The -y 标志跳过安装提示以实现无缝启动
3. 环境检测：自动检测Python 3.10+安装
4. 虚拟环境：在temp目录中创建隔离的Python环境
5. 软件包安装：安装 markitdown-mcp 和依赖关系
6. 流程管理：生成和管理Python MCP服务器进程
7. 信号处理：正确处理终止信号
8. 缓存：重用虚拟环境以实现更快的后续运行

🧪 MCP检验员测试

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

# 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，则带转录）
• 🌐 Web：HTTP/HTTPS URL
• 🗃️ 存档：ZIP文件
• 📊 数据：CSV、JSON、XML

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

💡 备注：在Claude Desktop中看到“1个可用工具”是 正确的行为!

🐛 故障排除

服务器在启动时挂起

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

NPX缓存问题

Error: Package not found or outdated

解决方案：使用清除NPX缓存 npx clear-npx-cache 或使用 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_SETUP.md 适用于Windows）

📂 文件结构

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
• 仓库:
• 许可证：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规范
• 克劳德桌面版：用于MCP集成
• NPM社区：对于出色的NPX工具

______________________________________________________________________

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

这是MarkItDown MCP的非官方包装。有关Docker的官方版本，请访问 原始存储库.