Google Custom Search MCP

Google Custom Search MCP サーバー

サービスアカウント認証を使用して Google Custom Search API にアクセスできる、非同期 Python MCP（Model Context Protocol）サーバーです。

機能

• google_search：結果数を設定して Google Custom Search クエリを実行します
• サービスアカウント認証：Google サービスアカウント認証を使用します（API キーは非推奨になったため必須です）
• デュアル認証対応：ローカル開発ではファイルパス、CI/CD では Base64 を使用します
• ライブ統合テスト：Google Custom Search API に対する実際のテストを実行します
• FastMCP 統合：最新の FastMCP Python SDK を使用します
• Docker 対応：最小限のサイズを実現する Alpine Linux ベースの Docker イメージです
• UV 互換性：UV を使用した最新の Python パッケージ管理に対応しています

クイックスタート

前提条件

1. Google サービスアカウント：Google Cloud Console でサービスアカウントを作成します
2. Custom Search Engine ID：Programmable Search Engine で Custom Search Engine を作成します
3. Custom Search API の有効化：Google Cloud プロジェクトで API を有効にします

インストール

# Clone the repository
git clone <your-repo-url>
cd google-custom-search-mcp

# Install with UV
uv sync

# Set environment variables
export GOOGLE_SERVICE_ACCOUNT_FILE=/path/to/your/service-account-key.json
export GOOGLE_SEARCH_ENGINE_ID=your-search-engine-id

# Run the server
uv run google-custom-search-mcp

CI/CD の場合（サービスアカウントを Base64 エンコード）

# Encode your service account JSON file to base64
base64 -i your-service-account-key.json -w 0 > service-account-base64.txt

# Use base64 encoded credential
export GOOGLE_SERVICE_ACCOUNT_BASE64=$(cat service-account-base64.txt)
export GOOGLE_SEARCH_ENGINE_ID=your-search-engine-id

# Run the server
uv run google-custom-search-mcp

Claude CLI でのクイックセットアップ

# Using file path (local development)
claude mcp add google-custom-search \
  -s user \
  uv run google-custom-search-mcp \
  -e GOOGLE_SERVICE_ACCOUNT_FILE=/path/to/service-account-key.json \
  -e GOOGLE_SEARCH_ENGINE_ID=your-search-engine-id

# Using base64 (CI/CD)
claude mcp add google-custom-search \
  -s user \
  uv run google-custom-search-mcp \
  -e GOOGLE_SERVICE_ACCOUNT_BASE64=your-base64-encoded-json \
  -e GOOGLE_SEARCH_ENGINE_ID=your-search-engine-id

Claude Desktop のセットアップ（手動）

Claude Desktop の設定に追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-custom-search": {
      "command": "uv",
      "args": ["run", "google-custom-search-mcp"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_FILE": "/path/to/your/service-account-key.json",
        "GOOGLE_SEARCH_ENGINE_ID": "your-search-engine-id"
      }
    }
  }
}

CLI の使用方法

サーバーでは、複数のトランスポートモードをサポートしています。

STDIO モード（デフォルト）

Claude Desktop またはコマンドラインで使用します。

python server.py  # Uses STDIO transport by default

HTTP モード

コンテナまたは Web サービスとしてデプロイする場合に使用します。

python server.py --transport http --host 0.0.0.0 --port 3000

CLI 引数

• --transport：トランスポートモード（stdio または http、デフォルト：stdio）
• --host：バインドする HTTP ホスト（デフォルト：0.0.0.0）
• --port：リッスンする HTTP ポート（デフォルト：3000）

使用例

# Run in STDIO mode (for Claude Desktop)
python server.py

# Run as HTTP server on default port
python server.py --transport http

# Run on custom port
python server.py --transport http --port 8080

# Run on specific interface
python server.py --transport http --host 127.0.0.1 --port 5000

Google サービスアカウントのセットアップ

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

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

2. サービスアカウントを作成する

1. 「IAM & Admin」>「Service Accounts」に移動します
2. 「Create Service Account」をクリックします
3. 名前と説明を入力します
4. 適切なロールを付与します（Custom Search API には CSE ロールが必要です）
5. 「Create Key」をクリックし、JSON キーファイルをダウンロードします

3. Custom Search Engine を作成する

1. Programmable Search Engine にアクセスします
2. 「Add」をクリックして新しい検索エンジンを作成します
3. 検索設定を構成します
4. コントロールパネルから Search Engine ID を取得します

4. 環境変数を設定する

ローカル開発（ファイルパス）：

export GOOGLE_SERVICE_ACCOUNT_FILE=/path/to/your/service-account-key.json
export GOOGLE_SEARCH_ENGINE_ID=your_actual_search_engine_id_here

CI/CD（Base64 エンコード）：

# Encode service account JSON to base64
base64 -i your-service-account-key.json -w 0 > service-account-base64.txt

export GOOGLE_SERVICE_ACCOUNT_BASE64=$(cat service-account-base64.txt)
export GOOGLE_SEARCH_ENGINE_ID=your_actual_search_engine_id_here

利用可能な関数

Google 検索

google_search({
  query: "Your search query",
  num_results?: 10  # Optional, 1-100 (default: 10)
})

レスポンス形式：

{
  "results": [
    {
      "title": "Result Title",
      "link": "https://example.com",
      "snippet": "Result description...",
      "display_link": "example.com"
    }
  ],
  "total_results": 100,
  "search_time": 0.5
}

Docker の使用方法

Docker イメージは、ポート 3000 で HTTP モードを自動的に実行します。

イメージをビルドする

docker build -t google-custom-search-mcp .

コンテナを実行する

コンテナはデフォルトでポート 3000 の HTTP モードで実行されます。

# Using file mount
docker run -d \
  -p 3000:3000 \
  -v /path/to/service-account-key.json:/app/service-account-key.json \
  -e GOOGLE_SERVICE_ACCOUNT_FILE=/app/service-account-key.json \
  -e GOOGLE_SEARCH_ENGINE_ID=your-engine-id \
  google-custom-search-mcp

# Using base64 environment variable (recommended for production)
docker run -d \
  -p 3000:3000 \
  -e GOOGLE_SERVICE_ACCOUNT_BASE64=your-base64-encoded-json \
  -e GOOGLE_SEARCH_ENGINE_ID=your-engine-id \
  google-custom-search-mcp

MCP クライアントは http://localhost:3000 でサーバーにアクセスできます。

Helm を使用した Kubernetes へのデプロイ

Helm チャートを使用すると、MCP サーバーを Kubernetes に簡単にデプロイできます。

クイックインストール

# Clone the repository
git clone https://github.com/fbettag/google-custom-search-mcp.git
cd google-custom-search-mcp

# Install using Helm
helm install google-custom-search-mcp ./charts/google-custom-search-mcp \
  --set google.searchEngineId="your-search-engine-id" \
  --set serviceAccount.base64.value="$(base64 -w 0 < your-service-account.json)" \
  --set serviceAccount.base64.enabled=true

デプロイをアップグレードする

helm upgrade google-custom-search-mcp ./charts/google-custom-search-mcp \
  --set google.searchEngineId="your-search-engine-id" \
  --set serviceAccount.base64.value="$(base64 -w 0 < your-service-account.json)" \
  --set serviceAccount.base64.enabled=true

アンインストール

helm uninstall google-custom-search-mcp

Values ファイルを使用する

values-prod.yaml ファイルを作成します。

# values-prod.yaml
replicaCount: 2

google:
  searchEngineId: "your-search-engine-id"

serviceAccount:
  base64:
    enabled: true
    value: "your-base64-encoded-service-account-json"

resources:
  requests:
    memory: "128Mi"
    cpu: "100m"
  limits:
    memory: "256Mi"
    cpu: "200m"

Values ファイルを指定してインストールします。

helm install google-custom-search-mcp . -f values-prod.yaml

既存のデプロイをアップグレードする

helm upgrade google-custom-search-mcp . \
  --set google.searchEngineId="your-search-engine-id" \
  --set serviceAccount.base64.value="$(base64 -i your-service-account.json -w 0)"

アンインストール

helm uninstall google-custom-search-mcp

Chart Configuration

Helm チャートでは、さまざまな設定オプションを使用できます。

Parameter	Description	Default
replicaCount	レプリカ数	1
image.repository	Docker イメージのリポジトリ	your-username/google-custom-search-mcp
image.tag	Docker イメージのタグ	latest
google.searchEngineId	Google Custom Search Engine の ID	""
serviceAccount.base64.enabled	Base64 エンコードされたサービスアカウントを使用するかどうか	true
serviceAccount.base64.value	Base64 エンコードされたサービスアカウント JSON	""
serviceAccount.existingFile.enabled	サービスアカウントにファイルマウントを使用するかどうか	false
serviceAccount.existingFile.path	サービスアカウントファイルのパス	""
service.type	Kubernetes のサービス種別	ClusterIP
service.port	サービスポート	3000
resources.requests	リソース要求	memory: 64Mi, cpu: 50m
resources.limits	リソース制限	memory: 128Mi, cpu: 100m

GitHub CI/CD の設定

リポジトリのシークレット

GitHub リポジトリに次のシークレットを追加します。

1. GOOGLE_SERVICE_ACCOUNT_BASE64：Base64 エンコードされたサービスアカウント JSON ファイル
2. GOOGLE_SEARCH_ENGINE_ID：お使いの Custom Search Engine の ID

GitHub 用のサービスアカウントのエンコード

# Encode service account JSON to base64 (no line wraps)
base64 -i your-service-account-key.json -w 0

# Copy the output and add as GitHub secret GOOGLE_SERVICE_ACCOUNT_BASE64

開発

開発環境のセットアップ

# Clone and setup
uv sync --dev

# Run live integration tests (requires valid credentials)
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=server --cov-report=html

# Linting
uv run ruff check .
uv run ruff format .

# Type checking
uv run mypy server.py

テスト

テストでは、実際の Google Custom Search API を使用したライブ統合テストを実行します。次の設定が必要です。

export GOOGLE_SERVICE_ACCOUNT_BASE64=your-base64-encoded-json
export GOOGLE_SEARCH_ENGINE_ID=your-search-engine-id

環境変数

Variable	Description	Required
GOOGLE_SERVICE_ACCOUNT_FILE	サービスアカウント JSON ファイルのパス	これ、または Base64 のいずれか
GOOGLE_SERVICE_ACCOUNT_BASE64	Base64 エンコードされたサービスアカウント JSON	これ、またはファイルパスのいずれか
GOOGLE_SEARCH_ENGINE_ID	Custom Search Engine の ID	はい

API の制限と料金

• Google Custom Search API では、1 日あたり 100 件の検索クエリを無料で利用できます
• 追加のクエリには課金設定が必要です
• サービスアカウントの割り当て上限はユーザーアカウントと同じです
• Google Custom Search の料金を参照してください

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します：git checkout -b feature/amazing-feature
3. 変更をコミットします：git commit -m 'Add amazing feature'
4. ブランチにプッシュします：git push origin feature/amazing-feature
5. プルリクエストを作成します

ライセンス

MIT License。詳細は LICENSE ファイルを参照してください。

サポート

問題や質問がある場合：

1. Google Custom Search のドキュメントを確認します
2. 既存の GitHub の Issue を確認します
3. 詳細な情報を添えて新しい Issue を作成します