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

Related MCP server: MCP Web Tools Server

提供ツール

• web_search: 現時点では接続確認用の mock 検索結果を返します。

• web_fetch: http / https URL を取得し、HTML から本文・タイトル・リンクを抽出します。

• web_find: web_fetch 相当の取得結果から指定文字列を検索します。

検索プロバイダー方針

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

初期実装候補:

• DuckDuckGo HTML 検索: API キー不要で始められる

• SearxNG: 社内またはローカルで立てるメタ検索。将来的な推奨候補

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

設定

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

現在の実装範囲

実装済み:

• 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 として返します。