Web

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 イメージで HTTP MCP サーバーとして起動:

docker build -t web-mcp .
docker run --rm -p 3000:3000 web-mcp

Docker Compose で起動:

cd mcp
docker compose up -d --build

HTTP MCP endpoint:

http://localhost:3000/mcp

stdio サーバーとして使う場合は、クライアントが node dist/index.js を起動します。 Docker で stdio として使う場合は、docker run -i --rm web-mcp node dist/index.js のように標準入力・標準出力をクライアントへ接続してください。

ビルド後、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: DuckDuckGo HTML 検索で実検索し、検索結果一覧を返します。
• 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
WEB_MCP_TRANSPORT	未指定	http を指定すると HTTP MCP サーバーとして起動
WEB_MCP_HTTP_HOST	0.0.0.0	HTTP MCP サーバーの bind host
WEB_MCP_HTTP_PORT	3000	HTTP MCP サーバーの port

現在の実装範囲

実装済み:

• MCP stdio server
• MCP Streamable HTTP server
• web_search / web_fetch / web_find の登録
• DuckDuckGo HTML による実検索
• web_search の time_range / include_domains / exclude_domains 対応
• 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 レスポンス

未実装:

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