document-converter

📄 Document Converter MCP

Cursor、VS Code、その他あらゆる MCP クライアントで、ドキュメントを Markdown に変換できます。
ローカルで処理 · クラウドへのアップロードなし · MarkItDown を利用

AI アシスタントがPDF、Office ファイル、スプレッドシート、メール、音声などを読み取れるようにし、整った Markdown として扱えます。これにより、バイナリ添付ファイルに苦労することなく、コンテンツの要約、検索、推論が可能になります。

目次

• 概要 📋
• ユースケース 💡
• 機能 ✨
• 対応形式 📎
• クイックインストール 🚀
  • 開始前の準備
  • Cursor 🖱️
  • VS Code 💻
  • Claude Desktop 🤖
  • 動作確認 ✅
• ツール 🛠️
• 使用例 💬
• ローカル開発 🧪
• 設定リファレンス ⚙️
• MCP レジストリ 📦
• トラブルシューティング 🔧
• ライセンス 📜

概要 📋

Document Converter MCP は、Model Context Protocol 向けに、Microsoft の MarkItDown ライブラリをラップした軽量な stdio サーバーです。

flowchart LR
  A[Your file on disk] --> B[Document Converter MCP]
  B --> C[MarkItDown]
  C --> D[Markdown in chat or .md file]

接続すると、エージェントはファイルをローカルで変換し、構造化されたテキストを返します。変換 API にデータが送信されることはありません。

ユースケース 💡

機能 ✨

• 🏠 ローカル優先 — ファイルはお使いのマシン内に保持され、サードパーティの変換サービスは使用しません
• 📎 幅広い形式に対応 — PDF、Office、CSV/JSON/テキスト、Outlook .msg、音声、YouTube など（MarkItDown 経由）
• 🔀 2 つのワークフロー — Markdown を元ファイルの隣に保存するか、チャット内だけでプレビューできます
• 📋 コピー＆ペーストで設定 — Cursor、VS Code、Claude Desktop 向けの手順に沿ったインストール
• 📦 レジストリに掲載 — 公式 MCP レジストリに登録されています
• ⚖️ MIT ライセンス — 個人利用、商用利用ともに無料です

サポートされている形式 📎

以下の形式は、インストール済みの追加パッケージを使用し、MarkItDown 0.1.6 で動作確認済みです。

markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]

uvx では解決できない Azure のプレリリースパッケージが含まれるため、markitdown[all] は使用していません。

完全にサポート（このプロジェクトの依存関係を使用）

限定的なサポート

サポート対象外

変換品質はソースファイルによって異なります。上流の詳細については、MarkItDown のドキュメントを参照してください。

クイックインストール 🚀

使用するエディターの手順に従ってください。以下の設定ではすべて同じコマンドを使用し、異なるのは JSON ファイルとラッパーキーのみです。

開始前に（すべてのエディター）

1. uv をインストールします（uvx が含まれています）。

   Windows（PowerShell）：

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   

   macOS／Linux：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. uvx が動作することを確認します（インストール後、新しいターミナルを開いてください）。

   uvx --version
   

3. 任意 — サーバーをテストします（出力はなくアイドル状態になります。stdio MCP では正常です）。

   uvx --from git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter --with markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription] document-converter-mcp
   

   停止するには Ctrl+C を押してください。

Cursor にインストールする 🖱️

1. Cursor → Settings → MCP を開きます（または、設定ファイルを直接編集します）。
2. 設定ファイルの場所：
   • Windows： %USERPROFILE%\.cursor\mcp.json
   • macOS： ~/.cursor/mcp.json
   • Linux： ~/.cursor/mcp.json
   • プロジェクトのみ： プロジェクトフォルダー内の .cursor/mcp.json
3. mcpServers 内にこのブロックを追加するか、既存の設定に統合します（JSON 全体をコピーしてください）。

{
  "mcpServers": {
    "document-converter": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter",
        "--with",
        "markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]",
        "document-converter-mcp"
      ]
    }
  }
}

4. ファイルを保存して、Cursor を再起動します（または、設定画面で MCP の横にある Reload をクリックします）。
5. 確認： Settings → MCP で document-converter が有効（緑色）になっていることを確認します。ツール：convert_to_markdown、preview_markdown。

cursor://anysphere.cursor-deeplink/mcp/install?name=document-converter&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJnaXQraHR0cHM6Ly9naXRodWIuY29tL1phaGlkLUFiYmFzLUFsaS1CYWlnL2RvY3VtZW50LWNvbnZlcnRlciIsIi0td2l0aCIsIm1hcmtpdGRvd25bcGRmLGRvY3gscHB0eCx4bHN4LHhscyxvdXRsb29rLGF1ZGlvLXRyYW5zY3JpcHRpb24seW91dHViZS10cmFuc2NyaXB0aW9uXSIsImRvY3VtZW50LWNvbnZlcnRlci1tY3AiXX0%3D

VS Code にインストールする 💻

組み込みの MCP サポートを利用するには、VS Code 1.102+ が必要です。

vscode://mcp/install?... はどこにも貼り付けないでください。 このリンクは VS Code では機能せず、spawn vscode://... ENOENT が発生する my-mcp-server-* のようなサーバーが作成されます。以下の JSON を使用してください。

方法 A — ユーザー設定をコピーして貼り付ける（推奨）

1. Ctrl+Shift+P → MCP: Open User Configuration
2. "command" が vscode:// で始まる、壊れたサーバーがあれば削除します（例：my-mcp-server-15e7e771）。
3. ファイルの内容を次の内容で置き換えます（または、既存のファイルに servers を統合します）。

{
  "servers": {
    "document-converter": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter",
        "--with",
        "markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]",
        "document-converter-mcp"
      ]
    }
  }
}

4. 保存してから、Ctrl+Shift+P → MCP: List Servers → document-converter を起動します。

uvx が見つからないというエラー（ENOENT）が発生する場合： where uvx（Windows）または which uvx（macOS/Linux）を実行し、"command" にフルパスを設定します。

"command": "C:\\Users\\YOUR_USER\\.local\\bin\\uvx.exe"

方法 B — VS Code でこのリポジトリを開く

1. git clone https://github.com/Zahid-Abbas-Ali-Baig/document-converter.git
2. File → Open Folder → document-converter を選択します
3. VS Code が .vscode/mcp.json を自動的に読み込みます
4. Ctrl+Shift+P → MCP: List Servers → document-converter を起動します

方法 C — サーバー追加ウィザード

Ctrl+Shift+P → MCP: Add Server → stdio を選択し、次の値を入力します。

Claude Desktop にインストール 🤖

1. Claude Desktop の設定ファイルを開きます：

   • Windows（Microsoft Store）： %LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.json
   • Windows（クラシック版）： %APPDATA%\Claude\claude_desktop_config.json
   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

   Windows Store 版 Claude では %APPDATA%\Claude\ が存在しない場合があります。その場合は、上記の Packages\Claude_*\... パスを使用してください。

2. Windows（Microsoft Store）— 初回のみのセットアップ： uvx --from git+... で Git を見つけられるようにします（Claude は MCP サーバーに最小限の PATH を渡します）。

   powershell -ExecutionPolicy Bypass -File scripts/setup-windows-uvx-git-shim.ps1
   

   または、リポジトリからこのスクリプトをダウンロードして実行します。Git for Windows を指す %USERPROFILE%\.local\bin\git.cmd が作成されます。

3. mcpServers 内に追加します（ルートにある既存の preferences はそのままにします）。

{
  "mcpServers": {
    "document-converter": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter",
        "--with",
        "markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]",
        "document-converter-mcp"
      ]
    }
  }
}

uvx が見つからない（ENOENT）場合： "command" に where uvx で確認できるフルパスを設定します。例：C:\\Users\\YOUR_USER\\.local\\bin\\uvx.exe。

4. Claude Desktop を完全に再起動します（トレイから終了して、再度開きます）。

動作確認 ✅

AI アシスタントに次のように尋ねます：

List the tools from document-converter MCP.

または：

Preview markdown for a PDF on my machine at C:\path\to\file.pdf

convert_to_markdown と preview_markdown が呼び出されることを確認してください。

ツール 🛠️

入力： お使いのマシン上のファイルへの絶対パスまたは相対パス（または YouTube のサポート対象 URL）。

出力： 要約、差分確認、または Git へのコミットに適した Markdown テキスト。

使用例 💬

MCP サーバー接続後に Cursor、VS Code、または Claude Desktop に貼り付けられる自然言語のプロンプトです。

PDF を変換して要約する

プロンプト：

Use document-converter to convert C:\Reports\annual-report.pdf to markdown,
then give me a 5-bullet executive summary.

動作： エージェントが convert_to_markdown を呼び出し、PDF の隣に annual-report.md を作成して、結果を要約します。

保存前に Word 文書をプレビューする

プロンプト：

Preview markdown for ./contracts/vendor-agreement.docx without saving.
Tell me if there is a termination clause.

動作： エージェントが preview_markdown を呼び出し、チャット内で内容を読み取って質問に回答します。ファイルは書き込まれません。

Excel を分析する

プロンプト：

Convert D:\data\sales-q1.xlsx to markdown and list the top 3 products by revenue.

動作： スプレッドシートの表が、モデルで解析して順位付けできる Markdown になります。

リリースノート用の PowerPoint

プロンプト：

Preview ./slides/product-launch.pptx as markdown and draft release notes
from the slide titles and bullet points.

Outlook メールの抽出

プロンプト：

Convert C:\Mail\customer-escalation.msg to markdown and extract action items.

バッチ形式のワークフロー（複数ファイル）

プロンプト：

Convert these to markdown and save beside each file:
- C:\Docs\spec-v2.pdf
- C:\Docs\api-reference.docx
- C:\Docs\metrics.xlsx
Then confirm the .md paths.

音声の文字起こし

プロンプト：

Preview markdown for ./recordings/standup-notes.mp3 and list decisions made.

audio-transcription エクストラが必要です（このプロジェクトの依存関係に含まれています）。

YouTube URL

プロンプト（チャットでプレビュー）：

Use preview_markdown on https://www.youtube.com/watch?v=EXAMPLE and summarize the main points.

プロンプト（ファイルに保存）：

Use convert_to_markdown on https://www.youtube.com/watch?v=EXAMPLE

動作： MarkItDown が視聴ページを取得し、タイトル、説明、メタデータを抽出します。利用可能な場合は、youtube-transcript-api を使用して字幕を追加します。convert_to_markdown は、サーバーの作業ディレクトリに youtube-EXAMPLE.md を保存します。

https://www.youtube.com/watch?v=... 形式を使用してください。youtube-transcription エクストラとインターネット接続が必要です。

Markdown 出力例（PDF）

変換後の例：

# Quarterly Results

Revenue increased 12% year over year driven by enterprise subscriptions.

## Highlights

- Net retention: 118%
- New logos: 240
- Gross margin: 74%

品質は、元の文書のレイアウトと MarkItDown のバージョンによって異なります。

ローカル開発 🧪

uvx ではなくローカルの仮想環境を使用する場合は、クローンしてください。

git clone https://github.com/Zahid-Abbas-Ali-Baig/document-converter.git
cd document-converter
python -m venv .venv

Windows（PowerShell）：

.venv\Scripts\activate
pip install -r requirements.txt

macOS / Linux：

source .venv/bin/activate
pip install -r requirements.txt

サーバーを直接実行します（stdio — MCP クライアントで使用）：

python server.py

設定リファレンス ⚙️

すべてのクライアントで、同じ基盤コマンドを実行します（完全な JSON の例はクイックインストール 🚀に記載しています。ここでは再掲しません）。

設定ファイルの場所

コピーして貼り付けられる設定： クイックインストール 🚀。

ローカルクローン（uvx なし）

クローンしてインストールします。手順はローカル開発 🧪を参照してください。その後、MCP クライアントが仮想環境の Python を参照するように設定します。

Windows：

{
  "mcpServers": {
    "document-converter": {
      "command": "REPO_PATH\\.venv\\Scripts\\python.exe",
      "args": ["REPO_PATH\\server.py"]
    }
  }
}

macOS / Linux：

{
  "mcpServers": {
    "document-converter": {
      "command": "REPO_PATH/.venv/bin/python",
      "args": ["REPO_PATH/server.py"]
    }
  }
}

MCP レジストリ 📦

公式 MCP レジストリに io.github.Zahid-Abbas-Ali-Baig/document-converter（v1.0.0）として登録されています。

• 🔍 レジストリの項目（v1.0.0）
• 📂 GitHub リポジトリ
• 📥 GitHub リリース v1.0.0（.mcpb バンドル）

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

依存関係の解決／markitdown[all] のエラー

azure-ai-contentunderstanding またはプレリリースに関するエラーが表示される場合は、設定から markitdown[all] を削除してください。代わりに、次を使用します。

markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription]

VS Code：spawn vscode://mcp/install?... ENOENT

VS Code のインストールリンクによって、uvx ではなく URL がコマンドとして書き込まれています。修正方法：

1. MCP: Open User Configuration（またはこのリポジトリ内の .vscode/mcp.json）を開きます
2. "command" が vscode:// で始まる my-mcp-server-* のような項目を削除します
3. このリポジトリの .vscode/mcp.json、またはVS Code にインストール 💻の JSON を使用します
4. MCP: List Servers → document-converter を再起動します

README の vscode://mcp/install?... リンクは使用しないでください。VS Code では信頼性がありません。

Claude Desktop：Git executable not found

uvx --from git+... の実行には、PATH 上に Git が必要です。Windows の Microsoft Store 版 Claude では、通常のターミナルで Git が動作する場合でも、C:\Program Files\Git\cmd が含まれていない最小限の PATH で MCP サーバーが起動されることがよくあります。

修正方法：Claude Desktop にインストール 🤖（手順 2）に記載されている一度だけ実行するシムスクリプトを実行します。%USERPROFILE%\.local\bin 内の uvx.exe と同じ場所に git.cmd が配置されます。

併せて確認してください：Git for Windows と uv がインストールされていること。PowerShell で事前に実行しておきます：uvx --from git+https://github.com/Zahid-Abbas-Ali-Baig/document-converter --with markitdown[pdf,docx,pptx,xlsx,xls,outlook,audio-transcription,youtube-transcription] document-converter-mcp（stdio では、アイドル状態は正常です）。

代替方法：uvx を使用できない場合は、ローカルクローン（uvx なし）を使用してください。

Failed to acquire MessagePort

これはこのサーバーではなく、Cursor または VS Code によるものです。

[MCPService] Error creating client: Failed to acquire MessagePort ...

確実な代替手段： ローカル開発 🧪 の手順に従い、ローカルクローンの MCP 設定を使用します。

インストールボタンが反応しない（Windows の Cursor）

インストールバッジではなく、Cursor へのインストール 🖱️ にある JSON をコピーして貼り付けてください。

ツールが表示されない

MCP を再読み込みするか、エディターを再起動します。サーバーが有効になっていること（赤色／無効ではないこと）を確認してください。

ライセンス 📜

MIT ライセンス — LICENSE を参照してください。

Copyright (c) 2026 Zahid Abbas Ali Baig