Google Search Tool

Google Search Tool

Playwright ベースの Node.js ツールです。検索エンジンのスクレイピング対策を回避して Google 検索を実行し、結果を抽出します。コマンドラインツールとして直接使用することも、MCP サーバーとして使用して、Claude などの AI アシスタントにリアルタイムの検索機能を提供することもできます。

中国語のドキュメント

主な機能

• ローカル SERP API の代替：有料の検索エンジン結果 API サービスに頼る必要はなく、すべての検索をローカルで実行します
• 高度なボット対策検出の回避技術：
  • 実際のユーザーの行動を模倣する、インテリジェントなブラウザー指紋管理
  • 検証の頻度を減らすため、ブラウザーの状態を自動的に保存・復元
  • ヘッドレス／ヘッドフルモードをスマートに切り替え、検証が必要な場合は自動的にヘッドフルモードに切り替え
  • デバイスとロケールの設定をランダム化して検出リスクを軽減
• 生 HTML の取得：Google のページ構造が変更された場合の分析やデバッグのため、検索結果ページの生 HTML（CSS と JavaScript を除去したもの）を取得できます
• ページのスクリーンショット：HTML コンテンツの保存時に、ページ全体のスクリーンショットを自動で撮影して保存します
• MCP サーバーとの統合：追加の API キーを必要とせず、Claude などの AI アシスタントにリアルタイムの検索機能を提供します
• 完全なオープンソースで無料：すべてのコードがオープンソースで、使用制限はなく、自由にカスタマイズおよび拡張できます

技術的な特徴

• TypeScript で開発されており、型安全性と優れた開発体験を提供します
• Playwright ベースのブラウザー自動化により、複数のブラウザーエンジンに対応します
• 検索キーワードをコマンドラインパラメーターで指定できます
• AI アシスタントとの統合に対応した MCP サーバー
• タイトル、リンク、スニペットを含む検索結果を返します
• 分析用に検索結果ページの生 HTML を取得するオプション
• JSON 形式で出力
• ヘッドレスモードとヘッドフルモードの両方に対応（デバッグ用）
• 詳細なログ出力
• 堅牢なエラー処理
• ボット対策検出を効果的に回避するためのブラウザー状態の保存と復元

インストール

# Install from source
git clone https://github.com/web-agent-master/google-search.git
cd google-search
# Install dependencies
npm install
# Or using yarn
yarn
# Or using pnpm
pnpm install

# Compile TypeScript code
npm run build
# Or using yarn
yarn build
# Or using pnpm
pnpm build

# Link package globally (required for MCP functionality)
npm link
# Or using yarn
yarn link
# Or using pnpm
pnpm link

Windows 環境に関する注意事項

このツールは Windows 環境向けに特別に調整されています。

1. Windows のコマンドプロンプトおよび PowerShell でコマンドラインツールが正常に動作するよう、.cmd ファイルが用意されています
2. ログファイルは Unix/Linux の /tmp ディレクトリではなく、システムの一時ディレクトリに保存されます
3. サーバーを正常にシャットダウンできるよう、Windows 固有のプロセスシグナル処理が追加されています
4. Windows のパス区切り文字に対応するため、クロスプラットフォームのファイルパス処理を使用します

使用方法

コマンドラインツール

# Direct command line usage
google-search "search keywords"

# Using command line options
google-search --limit 5 --timeout 60000 --no-headless "search keywords"

# Or using npx
npx google-search-cli "search keywords"

# Run in development mode
pnpm dev "search keywords"

# Run in debug mode (showing browser interface)
pnpm debug "search keywords"

# Get raw HTML of search result page
google-search "search keywords" --get-html

# Get HTML and save to file
google-search "search keywords" --get-html --save-html

# Get HTML and save to specific file
google-search "search keywords" --get-html --save-html --html-output "./output.html"

コマンドラインオプション

• -l, --limit <number>：結果数の上限（デフォルト：10）
• -t, --timeout <number>：タイムアウト（ミリ秒、デフォルト：60000）
• --no-headless：ブラウザーのインターフェースを表示します（デバッグ用）
• --remote-debugging-port <number>：リモートデバッグポートを有効にします（デフォルト：9222）
• --state-file <path>：ブラウザー状態ファイルのパス（デフォルト：./browser-state.json）
• --no-save-state：ブラウザーの状態を保存しません
• --get-html：結果を解析する代わりに、検索結果ページの生 HTML を取得します
• --save-html：HTML をファイルに保存します（--get-html と併用）
• --html-output <path>：HTML 出力ファイルのパスを指定します（--get-html および --save-html と併用）
• -V, --version：バージョン番号を表示します
• -h, --help：ヘルプ情報を表示します

出力例

{
  "query": "deepseek",
  "results": [
    {
      "title": "DeepSeek",
      "link": "https://www.deepseek.com/",
      "snippet": "DeepSeek-R1 is now live and open source, rivaling OpenAI's Model o1. Available on web, app, and API. Click for details. Into ..."
    },
    {
      "title": "DeepSeek",
      "link": "https://www.deepseek.com/",
      "snippet": "DeepSeek-R1 is now live and open source, rivaling OpenAI's Model o1. Available on web, app, and API. Click for details. Into ..."
    },
    {
      "title": "deepseek-ai/DeepSeek-V3",
      "link": "https://github.com/deepseek-ai/DeepSeek-V3",
      "snippet": "We present DeepSeek-V3, a strong Mixture-of-Experts (MoE) language model with 671B total parameters with 37B activated for each token."
    }
    // More results...
  ]
}

HTML 出力例

--get-html オプションを使用すると、出力に HTML コンテンツに関する情報が含まれます。

{
  "query": "playwright automation",
  "url": "https://www.google.com/",
  "originalHtmlLength": 1291733,
  "cleanedHtmlLength": 456789,
  "htmlPreview": "<!DOCTYPE html><html itemscope=\"\" itemtype=\"http://schema.org/SearchResultsPage\" lang=\"zh-CN\"><head><meta charset=\"UTF-8\"><meta content=\"dark light\" name=\"color-scheme\"><meta content=\"origin\" name=\"referrer\">..."
}

--save-html オプションも使用すると、出力に HTML の保存先パスが含まれます。

{
  "query": "playwright automation",
  "url": "https://www.google.com/",
  "originalHtmlLength": 1292241,
  "cleanedHtmlLength": 458976,
  "savedPath": "./google-search-html/playwright_automation-2025-04-06T03-30-06-852Z.html",
  "screenshotPath": "./google-search-html/playwright_automation-2025-04-06T03-30-06-852Z.png",
  "htmlPreview": "<!DOCTYPE html><html itemscope=\"\" itemtype=\"http://schema.org/SearchResultsPage\" lang=\"zh-CN\">..."
}

MCP サーバー

このプロジェクトは Model Context Protocol (MCP) サーバー機能を提供し、Claude などの AI アシスタントが Google 検索機能を直接利用できるようにします。MCP は、AI アシスタントが外部ツールやデータに安全にアクセスできるようにするオープンプロトコルです。

# Build the project
pnpm build

Claude Desktop との統合

1. Claude Desktop の設定ファイルを編集します:

   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
     • 通常は C:\Users\username\AppData\Roaming\Claude\claude_desktop_config.json にあります
     • Windows エクスプローラーのアドレスバーに %APPDATA%\Claude を入力すると直接アクセスできます

2. サーバー設定を追加し、Claude を再起動します

{
  "mcpServers": {
    "google-search": {
      "command": "npx",
      "args": ["google-search-mcp"]
    }
  }
}

Windows 環境では、以下の設定も使用できます:

1. cmd.exe と npx を使用する場合:

{
  "mcpServers": {
    "google-search": {
      "command": "cmd.exe",
      "args": ["/c", "npx", "google-search-mcp"]
    }
  }
}

2. フルパスで node を使用する場合（上記の方法で問題が発生した場合に推奨）:

{
  "mcpServers": {
    "google-search": {
      "command": "node",
      "args": ["C:/path/to/your/google-search/dist/src/mcp-server.js"]
    }
  }
}

注: 2 番目の方法では、C:/path/to/your/google-search を、google-search パッケージをインストールした実際のフルパスに置き換える必要があります。

統合後は、Claude で「最新の AI 研究を検索して」など、検索機能を直接使用できます。

プロジェクト構造

google-search/
├── package.json          # Project configuration and dependencies
├── tsconfig.json         # TypeScript configuration
├── src/
│   ├── index.ts          # Entry file (command line parsing and main logic)
│   ├── search.ts         # Search functionality implementation (Playwright browser automation)
│   ├── mcp-server.ts     # MCP server implementation
│   └── types.ts          # Type definitions (interfaces and type declarations)
├── dist/                 # Compiled JavaScript files
├── bin/                  # Executable files
│   └── google-search     # Command line entry script
├── README.md             # Project documentation
└── .gitignore            # Git ignore file

技術スタック

• TypeScript: 開発言語であり、型安全性とより良い開発体験を提供します
• Node.js: JavaScript/TypeScript コードを実行するためのランタイム環境
• Playwright: ブラウザ自動化用で、複数のブラウザをサポートします
• Commander: コマンドライン引数の解析とヘルプ情報の生成用
• Model Context Protocol (MCP): AI アシスタント統合のためのオープンプロトコル
• MCP SDK: MCP サーバーを実装するための開発ツールキット
• Zod: バリデーションと型安全性のためのスキーマ定義ライブラリ
• pnpm: ディスク容量とインストール時間を節約する効率的なパッケージ管理ツール

開発ガイド

すべてのコマンドはプロジェクトのルートディレクトリで実行できます:

# Install dependencies
pnpm install

# Install Playwright browsers
pnpm run postinstall

# Compile TypeScript code
pnpm build

# Clean compiled output
pnpm clean

CLI 開発

# Run in development mode
pnpm dev "search keywords"

# Run in debug mode (showing browser interface)
pnpm debug "search keywords"

# Run compiled code
pnpm start "search keywords"

# Test search functionality
pnpm test

MCP サーバー開発

# Run MCP server in development mode
pnpm mcp

# Run compiled MCP server
pnpm mcp:build

エラー処理

このツールには、堅牢なエラー処理メカニズムが組み込まれています:

• ブラウザの起動に失敗した場合のわかりやすいエラーメッセージ
• ネットワーク接続の問題に対する自動的なエラーステータスの返却
• 検索結果の解析失敗に関する詳細なログ
• タイムアウト時の正常な終了と有用な情報の返却

注意事項

一般的な注意事項

• このツールは学習および研究目的のみで使用してください
• Google の利用規約およびポリシーを遵守してください
• Google によるブロックを避けるため、リクエストを頻繁に送信しすぎないでください
• 一部の地域では Google にアクセスするためにプロキシが必要になる場合があります
• Playwright はブラウザをインストールする必要があり、初回使用時に自動的にダウンロードされます

状態ファイル

• 状態ファイルにはブラウザの Cookie やストレージデータが含まれるため、安全に保管してください
• 状態ファイルを使用することで、Google のボット検出を効果的に回避し、検索の成功率を向上させることができます

MCP サーバー

• MCP サーバーには Node.js v16 以上が必要です
• MCP サーバーを使用する際は、Claude Desktop が最新バージョンに更新されていることを確認してください
• Claude Desktop を設定する際は、MCP サーバーファイルへの絶対パスを使用してください

Windows 固有の注意事項

• Windows 環境では、初回の Playwright ブラウザのインストールに管理者権限が必要になる場合があります
• 権限の問題が発生した場合は、コマンドプロンプトまたは PowerShell を管理者として実行してみてください
• Windows ファイアウォールが Playwright ブラウザのネットワーク接続をブロックする場合があります。プロンプトが表示されたらアクセスを許可してください
• ブラウザの状態ファイルは、デフォルトでユーザーのホームディレクトリに .google-search-browser-state.json として保存されます
• ログファイルは、システムの一時ディレクトリ内の google-search-logs フォルダーに保存されます

商用SERP APIとの比較

SerpAPIなどの有料検索エンジン結果APIサービスと比べて、このプロジェクトには次のような利点があります。

• 完全無料：API呼び出し料金はかかりません
• ローカルで実行：すべての検索をローカルで実行し、サードパーティのサービスに依存しません
• プライバシー保護：検索クエリがサードパーティに記録されません
• カスタマイズ可能：完全なオープンソースで、必要に応じて変更や拡張ができます
• 使用制限なし：API呼び出し回数や頻度の制限を受けません
• MCP 統合：Claude などの AI アシスタントとの統合をネイティブにサポートします