URL to Markdown (Article Extractor)

url-to-markdown-mcp

npm： @kitedesk-erm/url-to-markdown-mcp · 公式 MCP Registry： io.github.kitedesk-erm/url-to-markdown-mcp

あらゆる URL を、AI アシスタントが使いやすいクリーンな Markdown またはプレーンテキストに変換する MCP サーバーです。 Claude、Cursor、Windsurf、Cline、VS Code Copilot など、あらゆる MCP クライアントに extract_url というツールを提供します。このツールはページを取得し、タイトル、著者、公開日、単語数、読了時間とともに、メインコンテンツのみを返します（ナビゲーション、広告、Cookie バナー、サイドバー、フッター、コメントは含みません）。

このサーバーは、ホスト型の Zyla API Hub の Article Extractor and URL to Markdown API を利用しています。Zyla API キーが必要です。7 日間の無料トライアルで取得できます。

• 高速：抽出時間は p50 が約 230 ms、p95 が約 650 ms（実際の記事 URL 20 件を対象に、2026-10-22 に測定）
• 見出し、リスト、コードブロック、絶対リンクを含む、LLM に適した Markdown。max_chars でトークン予算内に収められます
• 読み取り専用で SSRF 対策済み：localhost とプライベート IP は拒否されます
• コンパクト：ツール 1 つ、stdio トランスポート、ランタイム依存関係 2 つ（@modelcontextprotocol/sdk と zod）

ツール

extract_url

引数	型	デフォルト	説明
url	string、必須		公開されている http(s) URL（スキームは省略可能）
format	markdown | text | both	markdown	出力形式
max_chars	integer	上限なし	コンテンツを N 文字に切り詰めます
links	boolean	true	[text](url) 形式のリンクを保持します
images	boolean	false	 形式の画像を含めます

ツールは、短いメタデータヘッダーに続いてコンテンツを返します。

# How to Work Hard
Source: https://paulgraham.com/hwh.html
Words: 3313 (~14 min read) | truncated by max_chars

June 2021

It might not seem there's much to learn about how to work hard. Anyone who's been to school knows what it entails, ...

エラーは MCP ツールエラー（isError: true）として、読みやすいメッセージとともに返されるため、モデルは復旧できます。対象となるのは、キーの不足、プライベート URL または localhost URL、HTML 以外の対象、サイトへの接続不能、Zyla のクォータ超過またはレート制限、API の 502 エラーです。これには upstream_blocked（サイトが 401/403/429/451 またはボット確認ページを返した場合）と、empty_content（クライアント側でレンダリングされるページなど、単語数がほぼ 0 の場合）が含まれます。Zyla では成功した呼び出しのみが課金対象となるため、ブロックされたページやコンテンツが空のページは課金されません。

インストール

Node.js 18 以降が必要です。どのクライアントでも、キーを ZYLA_API_KEY に設定して、同じコマンド npx -y @kitedesk-erm/url-to-markdown-mcp を実行します。

Claude Desktop

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

{
  "mcpServers": {
    "url-to-markdown": {
      "command": "npx",
      "args": ["-y", "@kitedesk-erm/url-to-markdown-mcp"],
      "env": { "ZYLA_API_KEY": "your-zyla-api-key" }
    }
  }
}

Claude Code

claude mcp add url-to-markdown --env ZYLA_API_KEY=your-zyla-api-key -- npx -y @kitedesk-erm/url-to-markdown-mcp

Cursor

グローバル設定には ~/.cursor/mcp.json を、単一プロジェクトの設定には .cursor/mcp.json を使用します。

{
  "mcpServers": {
    "url-to-markdown": {
      "command": "npx",
      "args": ["-y", "@kitedesk-erm/url-to-markdown-mcp"],
      "env": { "ZYLA_API_KEY": "your-zyla-api-key" }
    }
  }
}

VS Code（GitHub Copilot エージェントモード）

.vscode/mcp.json に次の内容を追加します。VS Code がキーの入力を求め、安全に保存します。

{
  "inputs": [
    { "type": "promptString", "id": "zyla-key", "description": "Zyla API key", "password": true }
  ],
  "servers": {
    "url-to-markdown": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kitedesk-erm/url-to-markdown-mcp"],
      "env": { "ZYLA_API_KEY": "${input:zyla-key}" }
    }
  }
}

Windsurf、Cline、Continue、Zed およびその他のクライアント

ほとんどのクライアントでは、Claude Desktop と Cursor 向けに示したものと同じ mcpServers ブロックを使用します（Windsurf の場合は ~/.codeium/windsurf/mcp_config.json、Cline の場合は MCP Servers → Configure パネルを使用します）。一般的な形式は次のとおりです。

• command： npx
• args： ["-y", "@kitedesk-erm/url-to-markdown-mcp"]
• env： ZYLA_API_KEY=<your key>
• transport： stdio

Smithery / Docker

リポジトリには smithery.yaml と Dockerfile が含まれています。Docker で実行することもできます：docker build -t url-to-markdown-mcp . && docker run -i --rm -e ZYLA_API_KEY url-to-markdown-mcp。

ソースからのインストール

npm リリース前にインストールする場合は、ソースからビルドしてください：

git clone https://github.com/kitedesk-erm/url-to-markdown-mcp.git
cd url-to-markdown-mcp && npm install && npm run build
# then use "command": "node", "args": ["/absolute/path/to/url-to-markdown-mcp/dist/index.js"]

プロンプトの例

• 「https://go.dev/blog/go1.22 を読み、ループにどのような変更があったか要約してください。」
• 「これら3つの記事のテキストを取得して、それぞれの主張を比較してください」（各記事の max_chars: 6000 を指定）。
• 「このページを、タイトルと著者のフロントマター付きで Markdown のメモとして保存してください。」

制限事項

• JavaScript のレンダリングには対応していません。ブラウザー上でのみコンテンツを構築するページ（一部の SPA）では、取得できるテキストがわずかです。
• ペイウォールやボット対策で保護されたサイトからは、一般公開されている内容のみを取得します。ブロックまたはチャレンジされたリクエストでは upstream_blocked ツールエラーが返され、課金されません。
• Zyla のプランによって、クォータとレート制限が決まります。成功した（200）呼び出しのみがプランの利用量に計上されます。

開発

npm install
npm test          # build, then the raw JSON-RPC handshake + tools/list, a tool call via a local mock Zyla gateway, and metadata checks
npm run test:live # same, but the mock gateway forwards to the live extraction backend

テストではローカルのモックに対して偽のキーを使用するため、実際のキーは必要なく、保存もされません。Zyla のエンドポイントは、1つの定数 src/config.ts に設定されています。ZYLA_ENDPOINT で上書きできますが、テスト時に限ります。

GitHub のハンドルまたは名前空間を変更する場合： package.json の mcpName が唯一の正しい値です。npm run set-github-handle -- <handle> を実行すると、package.json、server.json、README.md、smithery.yaml が書き換えられます。その後、npm test ですべての値が一致していることを確認できます。これは MCP Registry でも必要です。

関連項目

• url-to-markdown-api：依存関係ゼロの JS/TS および Python クライアントに加え、RAG、エージェント、後で読むための使用例
• Zyla の掲載情報：Article Extractor and URL to Markdown API

ライセンス

MIT