WebSearch-MCP

WebSearch-MCP

stdio トランスポート経由でウェブ検索機能を提供する、Model Context Protocol（MCP）サーバーの実装です。このサーバーは WebSearch Crawler API と連携し、検索結果を取得します。

目次

• 概要
• インストール
• 設定
• セットアップと連携
  • クローラーサービスのセットアップ
    • 前提条件
    • クローラーサービスの起動
    • クローラー API のテスト
    • カスタム設定
  • MCP クライアントとの連携
    • クイックリファレンス：MCP 設定
    • Claude Desktop
    • Cursor IDE
    • Cline
• 使い方
  • パラメーター
  • 検索レスポンスの例
  • ローカルでのテスト
  • ライブラリとしての使用
• トラブルシューティング
  • クローラーサービスの問題
  • MCP サーバーの問題
• 開発
  • プロジェクト構成
  • npm への公開
• コントリビューション
• ライセンス

概要

WebSearch-MCP は、MCP に対応した AI アシスタントにウェブ検索機能を提供する Model Context Protocol サーバーです。Claude のような AI モデルがリアルタイムでウェブを検索し、あらゆるトピックについて最新の情報を取得できます。

このサーバーは、実際のウェブ検索を処理する Crawler API サービスと連携し、標準化された Model Context Protocol を使用して AI アシスタントと通信します。

インストール

Smithery 経由でのインストール

Smithery 経由で WebSearch を Claude Desktop に自動インストールするには：

npx -y @smithery/cli install @mnhlt/WebSearch-MCP --client claude

手動インストール

npm install -g websearch-mcp

または、インストールせずに使用します：

npx websearch-mcp

設定

WebSearch MCP サーバーは、環境変数を使用して設定できます：

• API_URL：WebSearch Crawler API の URL（デフォルト：http://localhost:3001）
• MAX_SEARCH_RESULT：リクエストで指定されていない場合に返す検索結果の最大数（デフォルト：5）

例：

# Configure API URL
API_URL=https://crawler.example.com npx websearch-mcp

# Configure maximum search results
MAX_SEARCH_RESULT=10 npx websearch-mcp

# Configure both
API_URL=https://crawler.example.com MAX_SEARCH_RESULT=10 npx websearch-mcp

セットアップと連携

WebSearch-MCP のセットアップでは、実際のウェブ検索を実行するクローラーサービスの設定と、MCP サーバーと AI クライアントアプリケーションとの連携という、主に 2 つの作業を行います。

クローラーサービスのセットアップ

WebSearch MCP サーバーで実際のウェブ検索を行うには、クローラーサービスが必要です。Docker Compose を使用すると、クローラーサービスを簡単にセットアップできます。

前提条件

• Docker と Docker Compose

クローラーサービスの起動

1. 次の内容で docker-compose.yml という名前のファイルを作成します：

version: '3.8'

services:
  crawler:
    image: laituanmanh/websearch-crawler:latest
    container_name: websearch-api
    restart: unless-stopped
    ports:
      - "3001:3001"
    environment:
      - NODE_ENV=production
      - PORT=3001
      - LOG_LEVEL=info
      - FLARESOLVERR_URL=http://flaresolverr:8191/v1
    depends_on:
      - flaresolverr
    volumes:
      - crawler_storage:/app/storage

  flaresolverr:
    image: 21hsmw/flaresolverr:nodriver
    container_name: flaresolverr
    restart: unless-stopped
    environment:
      - LOG_LEVEL=info
      - TZ=UTC

volumes:
  crawler_storage:

Mac Apple Silicon 向けの回避策

version: '3.8'

services:
  crawler:
    image: laituanmanh/websearch-crawler:latest
    container_name: websearch-api
    platform: "linux/amd64"
    restart: unless-stopped
    ports:
      - "3001:3001"
    environment:
      - NODE_ENV=production
      - PORT=3001
      - LOG_LEVEL=info
      - FLARESOLVERR_URL=http://flaresolverr:8191/v1
    depends_on:
      - flaresolverr
    volumes:
      - crawler_storage:/app/storage

  flaresolverr:
    image: 21hsmw/flaresolverr:nodriver
    platform: "linux/arm64"
    container_name: flaresolverr
    restart: unless-stopped
    environment:
      - LOG_LEVEL=info
      - TZ=UTC

volumes:
  crawler_storage:

2. サービスを起動します：

docker-compose up -d

3. サービスが実行中であることを確認します：

docker-compose ps

4. クローラー API のヘルスエンドポイントをテストします：

curl http://localhost:3001/health

期待されるレスポンス：

{
  "status": "ok",
  "details": {
    "status": "ok",
    "flaresolverr": true,
    "google": true,
    "message": null
  }
}

クローラー API は http://localhost:3001 で利用できます。

クローラー API のテスト

curl を使用して、クローラー API を直接テストできます：

curl -X POST http://localhost:3001/crawl \
  -H "Content-Type: application/json" \
  -d '{
    "query": "typescript best practices",
    "numResults": 2,
    "language": "en",
    "filters": {
      "excludeDomains": ["youtube.com"],
      "resultType": "all" 
    }
  }'

カスタム設定

docker-compose.yml ファイルの環境変数を変更して、クローラーサービスをカスタマイズできます：

• PORT：クローラー API がリッスンするポート（デフォルト：3001）
• LOG_LEVEL：ログレベル（選択肢：debug、info、warn、error）
• FLARESOLVERR_URL：FlareSolverr サービスの URL（Cloudflare の保護を回避するために使用）

MCP クライアントとの連携

クイックリファレンス：MCP の設定

各種クライアントでの MCP 設定について、クイックリファレンスを以下に示します。

{
    "mcpServers": {
        "websearch": {
            "command": "npx",
            "args": [
                "websearch-mcp"
            ],
            "environment": {
                "API_URL": "http://localhost:3001",
                "MAX_SEARCH_RESULT": "5" // reduce to save your tokens, increase for wider information gain
            }
        }
    }
}

Issue による Windows 向けの回避策

{
	"mcpServers": {
	  "websearch": {
            "command": "cmd",
            "args": [
				"/c",
				"npx",
                "websearch-mcp"
            ],
            "environment": {
                "API_URL": "http://localhost:3001",
                "MAX_SEARCH_RESULT": "1"
            }
        }
	}
  }

使用方法

このパッケージは stdio トランスポートを使用する MCP サーバーを実装しており、以下のパラメーターを持つ web_search ツールを提供します。

パラメーター

• query（必須）：検索するクエリ
• numResults（任意）：返す結果の数（デフォルト：5）
• language（任意）：検索結果の言語コード（例：'en'）
• region（任意）：検索結果の地域コード（例：'us'）
• excludeDomains（任意）：結果から除外するドメイン
• includeDomains（任意）：結果に含めるドメインのみを指定します
• excludeTerms（任意）：結果から除外する語句
• resultType（任意）：返す結果の種類（'all'、'news'、'blogs'）

検索レスポンスの例

検索レスポンスの例を以下に示します。

{
  "query": "machine learning trends",
  "results": [
    {
      "title": "Top Machine Learning Trends in 2025",
      "snippet": "The key machine learning trends for 2025 include multimodal AI, generative models, and quantum machine learning applications in enterprise...",
      "url": "https://example.com/machine-learning-trends-2025",
      "siteName": "AI Research Today",
      "byline": "Dr. Jane Smith"
    },
    {
      "title": "The Evolution of Machine Learning: 2020-2025",
      "snippet": "Over the past five years, machine learning has evolved from primarily supervised learning approaches to more sophisticated self-supervised and reinforcement learning paradigms...",
      "url": "https://example.com/ml-evolution",
      "siteName": "Tech Insights",
      "byline": "John Doe"
    }
  ]
}

ローカルでのテスト

WebSearch MCP サーバーをローカルでテストするには、付属のテストクライアントを使用できます。

npm run test-client

これにより、MCP サーバーと、検索クエリを入力して結果を確認できる簡単なコマンドラインインターフェイスが起動します。

テストクライアントの API_URL を設定することもできます。

API_URL=https://crawler.example.com npm run test-client

ライブラリとしての使用

このパッケージはプログラムから使用できます。

import { createMCPClient } from '@modelcontextprotocol/sdk';

// Create an MCP client
const client = createMCPClient({
  transport: { type: 'subprocess', command: 'npx websearch-mcp' }
});

// Execute a web search
const response = await client.request({
  method: 'call_tool',
  params: {
    name: 'web_search',
    arguments: {
      query: 'your search query',
      numResults: 5,
      language: 'en'
    }
  }
});

console.log(response.result);

トラブルシューティング

クローラーサービスの問題

• API に接続できない：クローラーサービスが稼働しており、設定された API_URL でアクセスできることを確認してください。
• 検索結果を取得できない：クローラーサービスのログを確認し、エラーがないか調べてください。

  docker-compose logs crawler
  

• FlareSolverr の問題：Cloudflare の保護を使用しているウェブサイトがあります。これに関連するエラーが表示された場合は、FlareSolverr が動作しているか確認してください。

  docker-compose logs flaresolverr
  

MCP サーバーの問題

• インポートエラー：最新バージョンの MCP SDK がインストールされていることを確認してください。

  npm install -g @modelcontextprotocol/sdk@latest
  

• 接続の問題：クライアントで stdio トランスポートが正しく設定されていることを確認してください。

開発

このプロジェクトで開発を行うには：

1. リポジトリをクローンします
2. 依存関係をインストールします：npm install
3. プロジェクトをビルドします：npm run build
4. 開発モードで実行します：npm run dev

サーバーは、付属の swagger.json ファイルで定義されている WebSearch Crawler API を必要とします。API が設定された API_URL で稼働していることを確認してください。

プロジェクト構成

• .gitignore：Git で無視するファイルを指定します（node_modules、dist、logs など）
• .npmignore：npm への公開時に含めないファイルを指定します
• package.json：プロジェクトのメタデータと依存関係
• src/：TypeScript のソースファイル
• dist/：コンパイル済みの JavaScript ファイル（ビルド時に生成）

npm への公開

このパッケージを npm に公開するには：

1. npm アカウントを作成し、ログインしていることを確認します（npm login）
2. package.json のバージョンを更新します（npm version patch|minor|major）
3. npm publish を実行します

.npmignore ファイルにより、公開するパッケージには必要なファイルのみが含まれます。

• dist/ 内のコンパイル済みコード
• README.md と LICENSE ファイル
• package.json

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

ISC