markdown-for-agents-mcp

MCP (Model Context Protocol)サーバーであり、完全なJavaScriptレンダリングでURLを取得し、AIエージェント向けにクリーンでトークン効率の良いMarkdownに変換します。

ほとんどのMCP取得ツールは単純なHTTPを使用するため、JavaScriptを実行せずにサーバーが送信した内容のみを確認します。これは静的サイトでは機能しますが、React、Vue、Angular、SPA、およびデータを動的に読み込むページでは、空または壊れたコンテンツを返してしまいます。このサーバーはPlaywrightを介して実際のChromiumブラウザを実行するため、抽出前にページ全体をレンダリングします。これは人間が目にするものと同じコンテンツです。

Playwrightとmarkdown-for-agentsライブラリを搭載しています。広告、ナビゲーション、定型文を削除し、生のHTMLと比較して最大80%少ないトークンで配信します。

なぜPlaywrightなのか？

トークン削減の例: 一般的なニュース記事ページは生のHTMLで約150 KB（約40,000トークン）です。Playwrightによるレンダリング、DOMの剪定、Markdown変換後、同じ記事は約2,000トークンになり、95%の削減となります。

目次

• なぜPlaywrightなのか？

• 機能

• インストール

• MCPクライアントの設定

• 利用可能なツール

  • fetch_url

  • fetch_urls

  • web_search

  • download_file

  • health_check

• CLIの使用方法

• 設定

• セキュリティ

• アーキテクチャ

• 開発

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

• 貢献

• 変更履歴

• ライセンス

機能

• JavaScriptレンダリング — Playwright駆動のChromiumが、抽出前にReact、Vue、Angular、およびJSを多用するページをレンダリングします

• 構造化出力 — ツールはテキスト応答に加えて、型定義されたstructuredContent（url、title、markdown、fetchedAt、contentSize）を返し、MCP SDK 1.11以降と互換性があります

• スマートコンテンツ抽出 — メインコンテンツブロック（main > article > #content > body）をスコアリングして選択し、サイドバー、ナビゲーション、広告を自動的に削除します

• トークン効率 — LLM対応のコンパクトなMarkdownを生成します。ベンチマークでは生のHTMLより最大80%少ないトークンであることが示されています

• ウェブ検索 — DuckDuckGo検索と、上位結果の取得・変換（オプション）

• LRUキャッシュ — 15分のTTLを持つ50 MBのメモリ内キャッシュにより、冗長な取得を回避します

• ドメインフィルタリング — トラッカー/ソーシャルドメインの組み込みブロックリスト。リクエストごとの許可/ブロックリストおよびサーバーレベルの許可リストモードをサポート

• バッチ取得 — 設定可能な並列処理による同時マルチURL取得

• HTTPサーバーモード — HTTPサーバーとして実行可能（--http [port]またはHTTP_PORT環境変数）、オプションでBearerトークン認証をサポート

• プロキシサポート — PLAYWRIGHT_PROXYを渡してPlaywrightのトラフィックをプロキシ経由でルーティング可能

• ヘルスモニタリング — health_checkツールでキャッシュと取得のメトリクスを公開

• ゼロコンフィグ — 初回実行時にChromiumが自動的にインストールされます

インストール

npm install -g markdown-for-agents-mcp

Chromiumはpostinstallスクリプトを介して自動的にダウンロードされます。失敗した場合はトラブルシューティングを参照してください。

グローバルにインストールせずにnpxを使用して実行することも可能です：

npx markdown-for-agents-mcp

MCPクライアントの設定

MCPクライアントの設定にサーバーを追加します。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または%APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します：

{
  "mcpServers": {
    "markdown": {
      "command": "markdown-mcp"
    }
  }
}

VS Code (Copilot / Continue)

ワークスペースまたはユーザーのsettings.jsonの該当するMCP拡張キーの下に追加します。例：

{
  "mcpServers": {
    "markdown": {
      "command": "markdown-mcp"
    }
  }
}

Cursor / Windsurf / Zed

MCP仕様を実装するすべてのクライアントがこのサーバーを使用できます。コマンドのエントリポイントはmarkdown-mcp（グローバルインストール後にPATHで利用可能）またはローカルビルドの場合はdist/index.jsへのフルパスです。

環境変数によるオーバーライド

{
  "mcpServers": {
    "markdown": {
      "command": "markdown-mcp",
      "env": {
        "FETCH_TIMEOUT_MS": "60000",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

HTTPサーバーモード

stdioの代わりに、標準のHTTPエンドポイントとしてサーバーを実行できます。共有デプロイメント、Docker、またはStreamable HTTPトランスポートを好むクライアントに便利です：

# Start on port 3456
markdown-mcp --http 3456

# Or use the env var
HTTP_PORT=3456 markdown-mcp

すべてのMCPトラフィックはPOST|GET|DELETE /mcpで処理されます。Bearerトークンを要求するには、MCP_AUTH_TOKENを設定します：

MCP_AUTH_TOKEN=mysecrettoken HTTP_PORT=3456 markdown-mcp

クライアントはすべてのリクエストでAuthorization: Bearer mysecrettokenを渡す必要があります。

利用可能なツール

fetch_url

完全なJavaScriptレンダリングで単一のURLを取得し、クリーンなMarkdownを返します。

引数:

例:

fetch_url(url="https://example.com/blog/post")

テキスト出力（常に存在し、後方互換性があります）：

# Blog Post Title

Source: https://example.com/blog/post

This is the main content of the article, stripped of navigation, ads, and boilerplate.

## Related Section

More content here...

---
*Converted by markdown-for-agents-mcp*

構造化出力（structuredContentを介してMCP SDK 1.11以降のクライアントで利用可能）：

{
  "url": "https://example.com/blog/post",
  "title": "Blog Post Title",
  "markdown": "# Blog Post Title\n\nSource: ...",
  "fetchedAt": "2026-04-06T17:00:00.000Z",
  "contentSize": 2048
}

fetch_urls

複数のURLを同時に取得し、URLごとに1セクションずつ結合されたMarkdownを返します。

引数:

例:

fetch_urls(urls=[
  "https://example.com/post1",
  "https://example.com/post2"
])

テキスト出力:

# Post 1 Title

Source: https://example.com/post1

...

---

# Post 2 Title

Source: https://example.com/post2

...

---

構造化出力（structuredContent経由）：

{
  "results": [
    {
      "url": "https://example.com/post1",
      "title": "Post 1 Title",
      "markdown": "...",
      "fetchedAt": "2026-04-06T17:00:00.000Z",
      "contentSize": 1820,
      "success": true
    },
    {
      "url": "https://example.com/post2",
      "title": "Post 2 Title",
      "markdown": "...",
      "fetchedAt": "2026-04-06T17:00:00.000Z",
      "contentSize": 2104,
      "success": true
    }
  ],
  "summary": { "total": 2, "succeeded": 2, "failed": 0 }
}

並列処理はMAX_CONCURRENT_FETCHES（デフォルト: 5）によって制御されます。

web_search

DuckDuckGoで検索し、オプションで上位結果をMarkdownとして取得します。ボット検知を回避するために単純なHTTPエンドポイントを使用します（検索自体にはPlaywrightを使用しません）。

引数:

例 — 検索のみ:

web_search(
  query="typescript tutorials",
  maxResults=5,
  allowedDomains=["typescriptlang.org", "github.com"]
)

例 — 検索と取得:

web_search(
  query="react hooks guide",
  fetchResults=true,
  maxResults=3
)

テキスト出力:

# Web Search Results

## Query: typescript tutorials
**Found 5 results in 1234ms**

### Results:

1. [TypeScript Handbook](https://www.typescriptlang.org/docs/)
   The TypeScript Handbook provides comprehensive documentation...

2. [Best TypeScript Tutorials](https://github.com/danistefanovic/build-your-own-typescript)
   Learn TypeScript by building your own compiler...

構造化出力（structuredContent経由）：

{
  "query": "typescript tutorials",
  "results": [
    { "title": "TypeScript Handbook", "url": "https://www.typescriptlang.org/docs/", "snippet": "...", "domain": "typescriptlang.org" }
  ],
  "fetchedContent": [
    { "url": "https://www.typescriptlang.org/docs/", "markdown": "..." }
  ],
  "durationMs": 1234
}

注: allowedDomainsおよびblockedDomains引数は検索結果のフィルタリングにのみ適用されます。結果が後続で取得される際には、サーバーレベルのBLOCKLIST_DOMAINS / USE_ALLOWLIST_MODE設定が引き続き適用されます。

download_file

URLからバイナリファイル（PDF、画像、ZIPなど）をダウンロードし、ローカルパスに保存します。単純なHTTPクライアントを使用し、Playwrightは不要です。SSRF保護とドメインブロックリストが適用されます。

引数:

例:

download_file(
  url="https://example.com/report.pdf",
  outputPath="/tmp/report.pdf"
)

出力:

{
  "savedPath": "/tmp/report.pdf",
  "sizeBytes": 204800,
  "mimeType": "application/pdf",
  "filename": "report.pdf"
}

注: /download/...のようなパスを持つURLは、fetch_urlではブロックされますが（バイナリダウンロードチェーンを避けるため）、このツールでは許可されます。HTMLページにはfetch_urlを使用してください。download_fileはtext/html応答を拒否します。

health_check

現在のサーバー状態、キャッシュメトリクス、取得統計を返します。監視やデバッグに便利です。

引数: なし

出力例:

{
  "status": "healthy",
  "cache": {
    "hits": 47,
    "misses": 15,
    "currentSize": 12,
    "totalBytes": 4194304,
    "maxBytes": 52428800
  },
  "metrics": {
    "totalFetches": 62,
    "successCount": 59,
    "errorCount": 3,
    "avgDuration": 1840,
    "cacheUtilization": 76
  }
}

CLIの使用方法

MCPプロトコルの外部で使用するためのスタンドアロンCLI（markdown-cli）が含まれています。

単一URL

markdown-cli https://example.com

複数URL（バッチモード）

markdown-cli -b https://example.com https://example.org https://example.net

ファイルに保存

markdown-cli https://example.com/article > article.md

バイナリファイルのダウンロード

markdown-cli -d -o /tmp/report.pdf https://example.com/report.pdf

コマンドリファレンス

設定

すべての設定は起動時に環境変数から読み込まれ、Zodで検証されます。無効な値は説明付きのエラーとともに非ゼロ終了します。

.env.exampleを.envにコピーして開始します：

cp .env.example .env

リファレンス

すべてのログはstderrに書き込まれ、stdoutはMCPプロトコルのためにクリーンに保たれます。

セキュリティ

デフォルトのドメインブロックリスト

トラッカー、広告ネットワーク、およびボットを積極的にブロックしたり低品質なコンテンツを提供するソーシャルプラットフォームの誤った取得を防ぐため、以下のドメインはデフォルトでブロックされています：

doubleclick.net, facebook.com, twitter.com, tiktok.com, hotjar.com, mixpanel.com, bit.lyなど約20ドメイン（完全なリストはsrc/utils/domainBlacklist.tsを参照）。

ブロックされたドメインを取得する必要がある場合は