Web MCP Server

Claude Code / Codex から利用する Web 検索・Web ページ取得用の MCP サーバーです。

コマンド

開発は Windows でも行えますが、運用時は Docker 上の Ubuntu で動かす前提です。

Linux / Docker コンテナ内の想定:

npm install
npm run build
npm run dev

Windows 開発環境:

npm install
npm run build
npm run dev

Docker イメージで起動:

docker build -t web-mcp .
docker run --rm -i web-mcp

MCP stdio サーバーなので、通常はクライアントが node dist/index.js を起動します。 Docker で使う場合も標準入力・標準出力をクライアントへ接続する必要があります。

ビルド後、MCP クライアントからは以下のように起動できます。

{
  "mcpServers": {
    "web-mcp": {
      "command": "node",
      "args": ["/app/mcp/dist/index.js"],
      "env": {
        "WEB_MCP_DEFAULT_RENDER": "auto",
        "WEB_MCP_FETCH_TIMEOUT_MS": "15000",
        "WEB_MCP_USER_AGENT": "LocalLLM-WebMCP/0.1"
      }
    }
  }
}

提供ツール

• web_search: 現時点では接続確認用の mock 検索結果を返します。
• web_fetch: http / https URL を取得し、HTML から本文・タイトル・リンクを抽出します。
• web_find: web_fetch 相当の取得結果から指定文字列を検索します。

検索プロバイダー方針

検索プロバイダーは無料で使えるものを優先します。

初期実装候補:

• DuckDuckGo HTML 検索: API キー不要で始められる
• SearxNG: 社内またはローカルで立てるメタ検索。将来的な推奨候補

Brave Search などの API キーが必要な provider は、無料枠が必要になった場合の拡張候補として扱います。

設定

環境変数で主な既定値を変更できます。

環境変数	既定値	用途
WEB_MCP_SERVER_NAME	web-mcp	MCP サーバー名
WEB_MCP_DEFAULT_MAX_RESULTS	10	web_search の既定件数
WEB_MCP_DEFAULT_MAX_CHARS	20000	web_fetch の既定最大文字数
WEB_MCP_DEFAULT_RENDER	auto	既定の render 指定
WEB_MCP_FETCH_TIMEOUT_MS	15000	静的 fetch のタイムアウト
WEB_MCP_BROWSER_TIMEOUT_MS	20000	将来のブラウザ取得用タイムアウト
WEB_MCP_USER_AGENT	LocalLLM-WebMCP/0.1	静的 fetch で送信する User-Agent

現在の実装範囲

実装済み:

• MCP stdio server
• web_search / web_fetch / web_find の登録
• AbortController による静的 fetch timeout
• 設定値からの User-Agent 送信
• redirect 後の final_url 返却
• 静的 HTML / XHTML / plain text fetch
• Content-Type 判定と未対応形式の error レスポンス
• Readability + Turndown による Markdown 風テキスト化
• Readability が本文を十分に抽出できない場合の DOM fallback 抽出
• max_chars / truncated 対応と Markdown 破損を抑える切り詰め
• include_links 指定時のリンク抽出
• fetch 失敗 / timeout の error レスポンス

未実装:

• 実検索 provider 連携
• Playwright によるブラウザレンダリング取得
• PDF テキスト抽出
• 取得済みページのキャッシュ

エラー形式

失敗時も MCP ツールとしては JSON を返し、error に原因を入れます。

{
  "error": {
    "code": "FETCH_TIMEOUT",
    "message": "The operation was aborted.",
    "url": "https://example.com",
    "retryable": true
  }
}

主な code は FETCH_FAILED、FETCH_TIMEOUT、UNSUPPORTED_CONTENT_TYPE、BROWSER_RENDER_FAILED です。 PDF は現時点では UNSUPPORTED_CONTENT_TYPE として返します。