# Google Web Search MCP Server

[![npm version](https://badge.fury.io/js/%40fukayatti0%2Fgooglesearch-mcp.svg)](https://badge.fury.io/js/%40fukayatti0%2Fgooglesearch-mcp)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

Google Custom Search API を使用した Model Context Protocol (MCP) サーバーです。gemini-cli と google/genai の`google_web_search`ツールと完全互換性があります。

## 特徴

- gemini-cli 互換: `google_web_search`ツールを完全再現
- google/genai 互換: Google GenAI SDK の検索機能と同等
- 構造化された結果: 引用付きの詳細な検索結果
- メタデータサポート: Open Graph データ、公開日時、画像情報を含む
- エラーハンドリング: 詳細なエラーメッセージとトラブルシューティング情報

## セットアップ

### 1. 依存関係のインストール

```bash
npm install -g @fukayatti0/googlesearch-mcp
```

### 2. 環境変数の設定

以下の環境変数を設定してください：

```bash
export GOOGLE_API_KEY="your_google_api_key"
export CUSTOM_SEARCH_ENGINE_ID="your_custom_search_engine_id"
```

### 3. Google Custom Search API の設定

1. [Google Cloud Console](https://console.cloud.google.com/)でプロジェクトを作成
2. Custom Search JSON API を有効化
3. API キーを作成
4. [Programmable Search Engine](https://programmablesearchengine.google.com/)でカスタム検索エンジンを作成
   - ウェブ全体を検索を有効にする（`*`を検索対象に追加）
5. 検索エンジン ID を取得。

## 使用方法

### MCP クライアントでの使用

このサーバーは以下のツールを提供します：

#### `google_web_search` (gemini-cli 互換)

Google Web 検索します。gemini-cli の`google_web_search`ツールと同じインターフェースです。

パラメータ:

- `query` (string, 必須): 検索クエリ

例:

```python
google_web_search(query="latest advancements in AI-powered code generation")
```

#### `google_search` (後方互換性)

Google 検索します。追加のパラメータをサポートします。

パラメータ:

- `query` (string, 必須): 検索クエリ
- `num_results` (number, オプション): 返す結果の数 (デフォルト: 10, 最大: 10)

例:

```json
{
  "name": "google_search",
  "arguments": {
    "query": "TypeScript MCP server",
    "num_results": 5
  }
}
```

## 出力形式

検索結果は以下の構造化された形式で返されます：

```markdown
# Web Search Results for "your query"

Found 1,234,567 results in 0.45 seconds

## 1. Page Title

**URL:** https://example.com/page
**Domain:** example.com
**Snippet:** Brief description of the page content...
**Description:** More detailed Open Graph description if available
**Published:** 2024-01-15T10:30:00Z
**Image:** https://example.com/image.jpg

---

## Sources

[1] Page Title - https://example.com/page
[2] Another Page - https://example.com/another
```

## MCP 設定例

### Claude Desktop / Kiro

```json
{
  "mcpServers": {
    "google-web-search": {
      "command": "node",
      "args": ["/path/to/googlesearch-mcp/build/index.js"],
      "env": {
        "GOOGLE_API_KEY": "your_google_api_key",
        "CUSTOM_SEARCH_ENGINE_ID": "your_custom_search_engine_id"
      }
    }
  }
}
```

### uvx 経由での実行

```json
{
  "mcpServers": {
    "google-web-search": {
      "command": "npx",
      "args": ["@fukayatti0/googlesearch-mcp"],
      "env": {
        "GOOGLE_API_KEY": "your_google_api_key",
        "CUSTOM_SEARCH_ENGINE_ID": "your_custom_search_engine_id"
      }
    }
  }
}
```

## gemini-cli との互換性

この MCP サーバーは、gemini-cli の`google_web_search`ツールと完全に互換性があります。

- 同じツール名: `google_web_search`
- 同じパラメータ: `query`のみ
- 同じ出力形式: 構造化された Markdown 形式
- 同じ機能: Web 検索結果の要約と引用

gemini-cli から移行する場合、設定を変更するだけで同じ機能を利用できます。

## トラブルシューティング

### よくあるエラー

1. API Key not found: `GOOGLE_API_KEY`環境変数が設定されていません
2. Custom Search Engine ID not found: `CUSTOM_SEARCH_ENGINE_ID`環境変数が設定されていません
3. API quota exceeded: 1 日 100 クエリの無料枠を超過しました
4. Invalid API key: API キーが無効または権限がありません

### 制限事項

- 無料枠: 1 日 100 クエリまで無料
- 結果数: 最大 10 件まで（Google Custom Search API の制限）
- レート制限: 秒間 100 クエリまで

## License

This project is licensed under the Apache 2.0 License. See the [LICENSE](LICENSE) file for details.