Markitdown MCP Npx

🚀 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 版本，請訪問 原始倉庫。