HTML to Markdown MCP Server

HTML から Markdown への MCP サーバー

HTML のウェブページを整った Markdown 形式に変換する MCP（Model Context Protocol）サーバーです。テーブル、画像、重要なコンテンツを保持しながら HTML のサイズを約 90～95％削減でき、AI のコンテキストに最適です。

特長

• URL の HTML を整った Markdown に変換
• テーブル、画像、リンクを保持
• 不要な要素（スクリプト、スタイル、ナビゲーション、フッター、ヘッダー）を削除
• 大幅なサイズ削減（通常 90～95％圧縮）
• 画像、テーブル、リンクの設定が可能
• 堅牢な抽出を実現するため、trafilatura と BeautifulSoup4 を使用
• ストリーム処理により、大きなページを効率的に処理
• サイズ制限により、過度に大きなコンテンツのダウンロードを防止（1MB～50MB）
• オプションのキャッシュにより、同じ URL の変換を繰り返す際の処理を高速化
• 🌐 Playwright によるブラウザモード - JavaScript を多用するサイトや認証が必要なページに対応
  • JavaScript を実行（SPA：React、Vue、Angular に最適）
  • ブラウザのプロファイルと Cookie を使用（認証が必要なページにアクセス可能）
  • Chrome、Firefox、WebKit に対応
  • 動的コンテンツ向けに待機方法を設定可能

インストール

前提条件

• Python 3.10 以降
• uv パッケージマネージャー（推奨）または pip

uv でインストール（推奨）

# Clone the repository
git clone <your-repo-url>
cd html2md

# Install dependencies
uv pip install -e .

# Install Playwright browsers (required for browser mode)
playwright install chromium

pip でインストール

# Clone the repository
git clone <your-repo-url>
cd html2md

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# Install Playwright browsers (required for browser mode)
playwright install chromium

Docker でインストール（本番環境に推奨）

html2md を使う最も簡単な方法は Docker です。

# Build the image
docker build -t html2md .

# Or use pre-built image (when published)
docker pull your-registry/html2md:latest

Claude Desktop では、Docker を使うように設定します。

{
  "mcpServers": {
    "html2md": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "html2md"
      ]
    }
  }
}

Docker イメージの特長：

• Playwright と Chromium をインストール済み
• サイズを最小限（約 1GB）に最適化
• セキュリティのため、root 以外のユーザーを使用
• すぐに使用可能。追加のセットアップは不要

設定

サーバーを Claude Desktop の設定ファイルに追加します。

macOS

~/Library/Application Support/Claude/claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "html2md": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/html2md",
        "run",
        "html2md"
      ]
    }
  }
}

Windows

%APPDATA%/Claude/claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "html2md": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\absolute\\path\\to\\html2md",
        "run",
        "html2md"
      ]
    }
  }
}

Linux

~/.config/Claude/claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "html2md": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/html2md",
        "run",
        "html2md"
      ]
    }
  }
}

使用方法

設定すると、MCP サーバーが Claude Desktop で利用できるようになります。html_to_markdown ツールを使用できます。

例 1：基本的な変換

Convert this webpage to markdown: https://example.com/article

例 2：オプションを指定した変換

Use the html_to_markdown tool with:
- url: https://example.com/docs
- include_images: false
- include_tables: true

例 3：JavaScript を多用するサイトでのブラウザモード

Use the html_to_markdown tool with:
- url: https://spa-application.com
- fetch_method: playwright
- wait_for: networkidle

例 4：認証が必要なページへのアクセス

Use the html_to_markdown tool with:
- url: https://private-site.com/dashboard
- fetch_method: playwright
- use_user_profile: true
- browser_type: chromium

注： use_user_profile=true を指定する場合は、実行前に Chrome を終了してください。

ツールのパラメーター

基本パラメーター：

• url（必須）：変換するウェブページの URL
• include_images（任意、デフォルト：true）：Markdown に画像を含める
• include_tables（任意、デフォルト：true）：Markdown にテーブルを含める
• include_links（任意、デフォルト：true）：Markdown にリンクを含める
• timeout（任意、デフォルト：30）：リクエストのタイムアウト（秒）（5～120）

パフォーマンス関連のパラメーター：

• max_size（任意、デフォルト：10MB）：ダウンロードするコンテンツの最大サイズ（バイト）（1MB～50MB）
• use_cache（任意、デフォルト：false）：キャッシュを有効にして、繰り返しの変換を高速化
• cache_ttl（任意、デフォルト：3600）：キャッシュの有効期間（秒）（60～86400）

ブラウザモードのパラメーター：

• fetch_method（任意、デフォルト："fetch"）：取得方法。"fetch"（高速）または "playwright"（JavaScript、認証に対応）
• browser_type（任意、デフォルト："chromium"）：使用するブラウザー。"chromium"、"firefox"、"webkit" のいずれか
• headless（任意、デフォルト：true）：ヘッドレスモードでブラウザーを実行
• wait_for（任意、デフォルト："networkidle"）：待機方法。"load"、"domcontentloaded"、"networkidle" のいずれか
• use_user_profile（任意、デフォルト：false）：Cookie を含むブラウザーのプロファイルを使用（Chrome を終了しておく必要があります）

開発

開発用依存関係をインストール

uv pip install -e ".[dev]"

テストを実行

pytest

コードをフォーマット

# Format with black
black src/ tests/

# Lint with ruff
ruff check src/ tests/

型チェック

mypy src/

アーキテクチャ

このプロジェクトは、主に次の 3 つのモジュールで構成されています。

converter.py

HTML から Markdown への変換機能の中核です：

• fetch_html()：URL から HTML をダウンロードします
• clean_html()：BeautifulSoup を使って不要な要素を削除します
• convert_to_markdown()：trafilatura を使って、クリーニング済みの HTML を Markdown に変換します
• html_to_markdown()：すべてのステップを組み合わせたメインのワークフローです

server.py

MCP サーバーの実装です：

• html_to_markdown ツールを登録します
• ツール呼び出しとエラーレスポンスを処理します
• stdio トランスポートを使って非同期 MCP サーバーを実行します

utils.py

ユーティリティ関数です：

• キャッシュ用のハッシュ計算
• テキストの書式設定と切り詰め
• ドメインの抽出
• ファイル名のサニタイズ

cache.py

メモリ内キャッシュシステムです：

• TTL をサポートする SimpleCache クラス
• グローバルキャッシュインスタンスの管理
• 古いエントリの自動期限切れ
• URL とパラメーターに基づくハッシュをキャッシュキーとして使用

browser.py

Playwright によるブラウザー自動化です：

• fetch_html_playwright() - 非同期のブラウザーベースの HTML 取得
• Chromium、Firefox、WebKit をサポート
• 認証済みアクセスのためのユーザープロファイル連携
• 動的コンテンツ向けの待機方法を設定可能

トラブルシューティング

Claude Desktop にサーバーが表示されない

1. claude_desktop_config.json 内のパスが絶対パスで、正しいことを確認します
2. Claude Desktop を完全に再起動します
3. Claude Desktop のログでエラーを確認します

インストールの問題

# Verify Python version
python --version  # Should be 3.10+

# Try reinstalling dependencies
uv pip install --force-reinstall -e .

変換エラー

• タイムアウトエラー：timeout パラメーターの値を増やします
• コンテンツが空：一部のウェブサイトでは自動リクエストがブロックされる場合や、JavaScript によるレンダリングが必要な場合があります
  • 解決策：fetch_method: playwright を使用して JavaScript を実行します
• 解析エラー：ウェブページの構造が通常と異なるか、正しくない可能性があります
• コンテンツが大きすぎる：max_size パラメーターの値を増やします（最大 50MB）。または、ページが制限を超えている可能性があります
• キャッシュの問題：最新のコンテンツが必要な場合は、use_cache: false でキャッシュを無効にします

ブラウザーモードの問題

• Playwright がインストールされていない：playwright install chromium を実行します
• ブラウザーの起動に失敗する：十分な権限とディスク容量があることを確認します
• ユーザープロファイルのエラー：use_user_profile: true を使用する前に、Chrome が完全に終了していることを確認します
• ページが完全に読み込まれない：別の wait_for 戦略を試します：
  • "load" - 最速です。ページの読み込みイベントを待ちます
  • "domcontentloaded" - DOM の準備ができるまで待ちます
  • "networkidle" - 最も遅いものの、最も信頼性が高く、ネットワークがアイドル状態になるまで待ちます
• 認証が機能しない：browser_type: chromium と use_user_profile: true を使用していることを確認します

パフォーマンス

一般的な変換結果：

• 元の HTML：~500KB - 2MB
• Markdown 出力：~25KB - 100KB
• 圧縮率：90-95%
• 処理時間：2-10 秒（ページサイズとネットワークによって異なります）

ライセンス

MIT

貢献

貢献を歓迎します！お気軽にイシューやプルリクエストを送信してください。

クレジット

以下を使用して構築されています：

• MCP SDK - Model Context Protocol
• trafilatura - ウェブコンテンツの抽出
• BeautifulSoup4 - HTML の解析