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 イメージで 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"
      }
    }
  }
}

Related MCP server: mcp-web-tools

提供ツール

• web_search: DuckDuckGo HTML 検索で実検索し、検索結果一覧を返します。

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

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

検索プロバイダー方針

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

現在の実装:

• DuckDuckGo HTML 検索: API キー不要で利用

将来候補:

• SearxNG: 社内またはローカルで立てるメタ検索

• Brave Search などの API キーが必要な provider は、無料枠が必要になった場合の拡張候補

設定

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

現在の実装範囲

実装済み:

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