MarkItDown-MCP-NPX

MarkItDown-MCP-NPX

Microsoft の MarkItDown MCP サーバー用 NPX ラッパー - Docker は不要です！

このパッケージは、Microsoft の markitdown-mcp 用の NPX 対応ラッパーを提供し、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 を使用する（推奨 - インストール不要！）

# 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 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

初回セットアップの検証

# 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. 自動確認：-y フラグによりインストール確認プロンプトを省略し、シームレスに起動します
3. 環境の検出：Python 3.10 以降のインストールを自動的に検出します
4. 仮想環境：一時ディレクトリに分離された Python 環境を作成します
5. パッケージのインストール：markitdown-mcp と依存関係をインストールします
6. プロセス管理：Python MCP サーバープロセスを起動して管理します
7. シグナル処理：終了シグナルを適切に処理します
8. キャッシュ：以降の実行を高速化するため、仮想環境を再利用します

🧪 MCP Inspector でのテスト

MCP Inspector を使用してサーバーをテストできます：

# 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 が提供するツールは、convert_to_markdown という1 つのツールのみです
✓ 汎用コンバーター：このツール 1 つですべてのファイル形式に対応します：

• 📄 ドキュメント：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 つ」と表示されるのは、正しい動作です！

🐛 トラブルシューティング

サーバーが起動時にハングする

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 <number> で別のポートを指定してください

NPX キャッシュの問題

Error: Package not found or outdated

解決方法：npx clear-npx-cache で NPX キャッシュをクリアするか、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 の場合は WINDOWS_SETUP.md を参照）

📂 ファイル構成

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
• リポジトリ：GitHub
• ライセンス：MIT
• Node.js：>=16.0.0
• Python：>=3.10

🤝 貢献

これは、Microsoft の MarkItDown MCP サーバーを非公式にラップしたものです。MarkItDown のコア機能に関する問題については、元のリポジトリを参照してください。

このラッパー固有の問題については：

1. トラブルシューティングのセクションを確認してください
2. Python と Node.js がインストールされていることを確認してください
3. MCP Inspector でテストしてください
4. GitHub で問題を報告してください

🙏 謝辞

• Microsoft AutoGen Team：MarkItDown と MCP サーバーを作成してくださったことに感謝します
• Model Context Protocol：MCP 仕様に感謝します
• Claude Desktop：MCP との統合に感謝します
• NPM Community：素晴らしい NPX ツールに感謝します

---

✨ すぐに使えます：npx -y markitdown-mcp-npx を実行してください

これは MarkItDown MCP の非公式ラッパーです。公式の Docker 版については、元のリポジトリをご覧ください。