Html2md MCP

🚀 HTML to Markdown MCP Server

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に最適）。
  • クッキーを含むブラウザプロファイルを使用して、認証済みページにアクセスできます。
  • Chrome、Firefox、WebKitをサポートします。
  • 動的コンテンツに対する設定可能な待機戦略があります。

📦 インストール

前提条件

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

uvを使ったインストール（推奨）

# リポジトリをクローン
git clone <your-repo-url>
cd html2md

# 依存関係をインストール
uv pip install -e .

# Playwrightのブラウザをインストール（ブラウザモードに必要）
playwright install chromium

pipを使ったインストール

# リポジトリをクローン
git clone <your-repo-url>
cd html2md

# 仮想環境を作成
python -m venv venv
source venv/bin/activate  # Windowsの場合: venv\Scripts\activate

# 依存関係をインストール
pip install -e .

# Playwrightのブラウザをインストール（ブラウザモードに必要）
playwright install chromium

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

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

# イメージをビルド
docker build -t html2md .

# または、事前にビルドされたイメージを使用（公開された場合）
docker pull your-registry/html2md:latest

Claude DesktopでDockerを使って設定するには、以下のようにします。

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

Dockerイメージの特徴:

• Chromiumを含むPlaywrightが事前にインストールされています。
• 最小サイズ（約1GB）に最適化されています。
• セキュリティのために非ルートユーザーで動作します。
• 追加の設定不要ですぐに使えます。

📚 ドキュメント

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"
      ]
    }
  }
}

💻 使用例

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

基本的な使用法

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

オプションを指定する場合

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

JavaScriptが多いサイトのブラウザモード

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

認証済みページへのアクセス

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"（JS、認証を扱う）
• browser_type（オプション、デフォルト: "chromium"）: 使用するブラウザ - "chromium"、"firefox"、または "webkit"
• headless（オプション、デフォルト: true）: ブラウザをヘッドレスモードで実行するかどうか
• wait_for（オプション、デフォルト: "networkidle"）: 待機戦略 - "load"、"domcontentloaded"、または "networkidle"
• use_user_profile（オプション、デフォルト: false）: クッキーを含むブラウザプロファイルを使用する（Chromeを閉じる必要があります）

🔧 技術詳細

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

uv pip install -e ".[dev]"

テストの実行

pytest

コードのフォーマット

# blackでフォーマット
black src/ tests/

# 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ツールを登録します。
• ツールの呼び出しとエラー応答を処理します。
• 標準入出力トランスポートで非同期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のログを確認してエラーを探します。

インストールに問題がある場合

# Pythonバージョンを確認
python --version  # 3.10以上である必要があります

# 依存関係を再インストールしてみる
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の解析