Google Search Mcp

Google Search MCP Server

自動 API キーローテーションとインテリジェントなクォータ管理機能を備えた、Google Search 機能を提供する Model Context Protocol（MCP）サーバーです。

機能

• 公式 Google Custom Search API との統合
• 1 日あたりの上限を増やすための API キーの自動ローテーション
• セッションやディレクトリをまたいだ永続的なクォータ追跡
• 多言語および位置情報への対応
• 高度な検索フィルター（日付、ファイルタイプ、特定サイト）
• SafeSearch によるコンテンツフィルタリング
• グローバル設定 — どこからでも利用可能
• Claude Desktop およびその他の MCP クライアントに対応

インストール

クイックセットアップ（推奨）

# Install the package globally
npm install -g @kyaniiii/google-search-mcp

# Run interactive setup
google-search-setup

これにより、以下が実行されます。

• ✅ Google API キーを対話形式で設定
• ✅ グローバル設定ファイルをセットアップ
• ✅ Claude Code と自動的に統合
• ✅ API キーごとに 1 日 100 回以上の無料検索を有効化

高度なインストール

git clone https://github.com/Fabien-desablens/google-search-mcp.git
cd google-search-mcp
npm install
npm run build
npm run setup

アンインストール

完全な削除

# Remove the package
npm uninstall -g @kyaniiii/google-search-mcp

# Remove from Claude Code
claude mcp remove google-search

# Remove configuration file (if desired)
npm run clean

注: API キーを保護するため、設定ファイル（~/.google-search-mcp.json）は更新時もアンインストール時も常に保持されます。設定を完全に削除したい場合に限り、npm run clean を使用してください。

設定

セットアップツールは、次の場所にグローバル設定ファイルを作成します。

• Windows: %USERPROFILE%\.google-search-mcp.json
• Linux/macOS: ~/.google-search-mcp.json

このファイルには、以下が含まれます。

• ✅ API キーと検索エンジン ID
• ✅ 永続的なクォータ追跡（再起動後も保持）
• ✅ 毎日 UTC の午前 0 時に自動リセット
• ✅ ディレクトリをまたいだ使用（どこからでも利用可能）

設定例

{
  "keys": [
    {
      "id": "key_1",
      "apiKey": "AIzaSy...",
      "searchEngineId": "abc123...",
      "dailyUsage": 45,
      "dailyLimit": 100,
      "lastReset": "2024-07-30",
      "isActive": true
    }
  ],
  "lastUpdated": "2024-07-30T15:30:00Z",
  "version": "1.0.0"
}

⚠️ 重要: 設定ファイル（~/.google-search-mcp.json）を手動で編集した場合、変更を反映するには Claude Desktop を再起動する必要があります。

Google API 認証情報の取得

1. Google Cloud プロジェクトを作成する

1. Google Cloud Console にアクセスします
2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します
3. 「Custom Search API」を有効にします

2. API キーを生成する

1. 「APIs & Services」>「Credentials」に移動します
2. 「Create Credentials」>「API Key」をクリックします
3. 生成されたキーをコピーします

3. Custom Search Engine を作成する

1. Google Programmable Search Engine にアクセスします
2. 「Get started」または「Add」をクリックします
3. 「Sites to search」に * を入力して、ウェブ全体を検索します
4. Search Engine ID をコピーします

4. 複数のキーで拡張する

• 各 Google Cloud プロジェクトでは、1 日あたり 100 回の無料検索が利用できます
• クォータを増やすには、複数のプロジェクトを作成します（例: 3 プロジェクト = 1 日あたり 300 回の検索）
• サーバーは利用可能なキーを自動的にローテーションします

Claude Code での使用方法

セットアップを実行すると、サーバーは Claude Code に自動的に設定されます。すぐに使用できます。

User: "Search for latest AI news from this week"
Claude: I'll search for the latest AI news using Google Search...

サーバーは、次のパラメーターを持つ google_search ツールを公開します。

必須パラメーター

• query (string): 検索クエリ

オプションのパラメーター

• num (number): 検索結果の数（1～10、デフォルト: 5）
• start (number): 検索結果の開始インデックス
• safe (string): SafeSearch のレベル（'off'、'active'）
• lr (string): 言語の制限（例: 'lang_en'、'lang_fr'）
• gl (string): 地理的位置（国コード: 'us'、'fr'、'uk'）
• dateRestrict (string): 期間（'d1'、'w1'、'm1'、'y1'）
• fileType (string): ファイルタイプのフィルター（'pdf'、'doc'、'ppt'）
• siteSearch (string): 特定のサイトを検索
• siteSearchFilter (string): サイトを含める（'i'）または除外する（'e'）
• cr (string): 国の制限（'countryUS'、'countryFR'）
• exactTerms (string): 含める完全一致のフレーズ
• excludeTerms (string): 除外する語句
• orTerms (string): 代替語句（OR 検索）
• sort (string): 日付順に並べ替え（'date'）
• searchType (string): 検索タイプ（画像検索の場合は 'image'）

例

基本的な検索

{
  "query": "artificial intelligence news"
}

高度な検索

{
  "query": "machine learning",
  "num": 10,
  "lr": "lang_en",
  "gl": "us",
  "dateRestrict": "m1",
  "fileType": "pdf"
}

サイト固有の検索

{
  "query": "typescript tutorial",
  "siteSearch": "stackoverflow.com",
  "siteSearchFilter": "i"
}

クォータ管理

サーバーは各レスポンスでリアルタイムのクォータ情報を提供します。

{
  "results": [...],
  "metadata": {
    "quotaStatus": {
      "totalUsed": 15,
      "totalLimit": 300,
      "keysStatus": [
        {
          "id": "key_1",
          "used": 15,
          "limit": 100,
          "remaining": 85,
          "active": true
        }
      ]
    }
  }
}

クォータ機能

• 毎日 UTC の午前 0 時に自動リセット
• 上限に達するとキーをインテリジェントにローテーション
• 無効になったキーはリセット後に自動的に再有効化
• サーバーの再起動後も永続的に追跡
• 料金は発生せず、無料枠の上限で停止

エラー処理

サーバーはさまざまなエラー状況を適切に処理します。

• クォータ超過：次に利用可能なキーへ自動的に切り替えます
• すべてのキーを使い切った場合：クォータ状況を含む、明確なエラーメッセージを返します
• 無効な API キー：そのキーを無効化し、ほかのキーで処理を続行します
• ネットワークエラー：詳細なエラー情報を返します

開発

前提条件

• Node.js 18+
• TypeScript
• Google Cloud アカウント

スクリプト

# Development mode with auto-reload
npm run dev

# Build for production
npm run build

# Start server
npm start

# Setup configuration
npm run setup

プロジェクト構成

google-search-mcp/
├── src/
│   ├── index.ts         # Entry point
│   ├── server.ts        # MCP server setup
│   ├── config.ts        # Configuration wrapper
│   ├── global-config.ts # Global config manager
│   └── tools/
│       └── search.ts    # Search implementation
├── build/               # Compiled JavaScript
├── setup.js             # Interactive setup tool
└── package.json

コントリビューション

コントリビューションを歓迎します。以下の手順に従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 該当する場合はテストを追加します
5. プルリクエストを送信します

ライセンス

MIT License — 詳細は LICENSE ファイルをご覧ください

サポート

問題、質問、コントリビューションについては、以下をご覧ください。 https://github.com/Fabien-desablens/google-search-mcp