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を使用する（推奨 - インストール不要！）

# 基本的な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バージョンとの比較

💻 使用例

基本的な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

🛠️ 利用可能なオプション

Usage: markitdown-mcp-npx [options]

Options:
  --http           Streamable 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
# - トランスポート: 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をインストールすると文字起こし可能）
• 🌐 Web: HTTP/HTTPS URL
• 🗃️ アーカイブ: ZIPファイル
• 📊 データ: CSV、JSON、XML

✓ URIパラメータ: http:、https:、file:、またはdata:のURIを受け付けます。

💡 注意: Claude Desktopで「1 tools available」と表示されるのは正常な動作です！

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

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

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パッケージの設定
├── 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のコア機能に関する問題は、元のリポジトリを参照してください。

このラッパーに固有の問題については、以下の手順を実行してください。

1. トラブルシューティングセクションを確認する
2. PythonとNode.jsのインストールを確認する
3. MCPインスペクターでテストする
4. GitHubで問題を開く

🙏 謝辞

• Microsoft AutoGenチーム: 元のMarkItDownとMCPサーバーを作成してくれた
• Model Context Protocol: MCP仕様の提供
• Claude Desktop: MCPの統合
• NPMコミュニティ: 素晴らしいNPXツールの提供

✨ 使い始める準備はできましたか？ 次のコマンドを実行してください: npx -y markitdown-mcp-npx

これはMarkItDown MCPの非公式ラッパーです。公式のDockerバージョンについては、元のリポジトリを参照してください。