SearchAPI Mcp

SearchAPI MCP Server

---

機能

🔍 検索エンジン

• Google Search - ウェブ検索結果、ナレッジグラフ、回答ボックス、関連する質問
• Google Videos - 再生時間、ソース、アップロード時刻によるフィルタリングが可能な動画検索
• Google AI Mode - 引用元と構造化コンテンツを含む、AI 生成の概要
• Google Maps - 場所、ビジネス、レビュー、位置情報の詳細
• Google Maps Place - 特定の場所の詳細情報（営業時間、写真、設備）
• Google Events - コンサート、会議、フェスティバル、地域のアクティビティを検索
• Google Flights - 包括的なフィルタリングと価格カレンダーを備えたフライト検索
• Google Flights Location Search - 空港コードの検索とオートコンプリート
• Google Travel Explore - 旅行先や旅行のインスピレーションを発見
• Google Hotels - 設備、評価、価格フィルターを備えた宿泊施設検索

🏗️ 本番環境対応のアーキテクチャ

• コネクションプーリング - httpx による効率的な HTTP 接続管理
• レスポンスキャッシュ - LRU による削除機能を備えた、TTL ベースの設定可能なキャッシュ
• 再試行ロジック - 一時的な障害に対する指数バックオフ
• サーキットブレーカー - 障害の連鎖を防ぐフェイルセーフパターン
• メトリクス収集 - リクエスト数、レイテンシ、キャッシュヒット率、エラー追跡
• ヘルスチェック - API 接続状況とサービスステータスを監視

⚙️ 設定とモニタリング

• Pydantic による検証 - 環境変数に対応した、型安全な設定
• 構造化ログ - 詳細なリクエストトレースに対応した、設定可能なログレベル
• リソース管理 - 自動クリーンアップと正常なシャットダウン
• 環境変数 - デプロイ先に応じた柔軟な設定

---

クイックスタート

前提条件

• Python 3.10 以降
• SearchAPI.io API キー（こちらから取得）

UV でインストール（推奨）

最も手早く始めるには、uvx を使用します。

# Set your API key
export SEARCHAPI_API_KEY="your_api_key_here"

# Run directly with uvx (no installation needed)
uvx --from git+https://github.com/RmMargt/searchAPI-mcp.git mcp-server-searchapi

---

インストール

方法 1：UV（推奨）

UV は最も高速で便利な方法です。

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/RmMargt/searchAPI-mcp.git
cd searchAPI-mcp

# Install dependencies
uv pip install -r requirements.txt

方法 2：pip

# Clone the repository
git clone https://github.com/RmMargt/searchAPI-mcp.git
cd searchAPI-mcp

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

方法 3：ソースから

git clone https://github.com/RmMargt/searchAPI-mcp.git
cd searchAPI-mcp

# Using uv
uv pip install httpx fastmcp python-dotenv pydantic pydantic-settings

# Or using pip
pip install httpx fastmcp python-dotenv pydantic pydantic-settings

---

設定

環境変数

プロジェクトのルートに .env ファイルを作成します。

# Required
SEARCHAPI_API_KEY=your_api_key_here

# Optional - API Configuration
SEARCHAPI_API_URL=https://www.searchapi.io/api/v1/search
TIMEOUT=30.0
MAX_RETRIES=3
RETRY_BACKOFF=1.0

# Optional - Cache Configuration
ENABLE_CACHE=true
CACHE_TTL=3600
CACHE_MAX_SIZE=1000

# Optional - Connection Pool
POOL_CONNECTIONS=10
POOL_MAXSIZE=10

# Optional - Monitoring
ENABLE_METRICS=true
LOG_LEVEL=INFO

MCP クライアントの設定

Claude Desktop

Claude Desktop の設定ファイルに追加します。

場所：

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

UV を使用（推奨）：

{
  "mcpServers": {
    "searchapi": {
      "command": "uvx",
      "args": [
        "--directory",
        "/absolute/path/to/searchAPI-mcp",
        "python",
        "mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Python を直接使用：

{
  "mcpServers": {
    "searchapi": {
      "command": "python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

仮想環境を使用：

{
  "mcpServers": {
    "searchapi": {
      "command": "/absolute/path/to/searchAPI-mcp/venv/bin/python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

VS Code（Continue、Cline）

ワークスペースの .vscode/mcp.json に追加するか、「MCP: Open User Configuration」コマンドを使用します。

{
  "servers": {
    "searchapi": {
      "command": "python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

UV を使用：

{
  "servers": {
    "searchapi": {
      "command": "uvx",
      "args": [
        "--directory",
        "/absolute/path/to/searchAPI-mcp",
        "python",
        "mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Zed Editor

~/.config/zed/settings.json に追加します。

{
  "context_servers": {
    "searchapi": {
      "command": {
        "path": "python",
        "args": [
          "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
        ],
        "env": {
          "SEARCHAPI_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Cline（VS Code 拡張機能）

Cline の設定で、MCP サーバーに追加します。

{
  "mcpServers": {
    "searchapi": {
      "command": "python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

汎用 MCP クライアント

MCP 対応のすべてのクライアントで使用できます。

# Using stdio transport (default)
python /path/to/searchAPI-mcp/mcp_server_refactored.py

# With environment variable
SEARCHAPI_API_KEY=your_key python mcp_server_refactored.py

---

利用可能なツール

ヘルスチェックとモニタリング

health_check

SearchAPI サービスの健全性とパフォーマンスを確認します。

戻り値：

• API の接続状態
• 応答レイテンシ
• サーキットブレーカーの状態
• キャッシュの統計情報
• リクエストのメトリクス

例：

{
  "api_status": {
    "status": "healthy",
    "latency_ms": 145.23,
    "circuit_breaker": "closed"
  },
  "cache_stats": {
    "size": 42,
    "max_size": 1000,
    "ttl": 3600
  },
  "metrics": {
    "request_count": 156,
    "error_count": 2,
    "cache_hit_rate": 0.67
  }
}

---

時刻と日付のユーティリティ

get_current_time

現在時刻と旅行日の候補を取得します。フライトやホテルの予約に不可欠です。

パラメーター：

• format - 日付形式：「iso」、「slash」、「chinese」、「timestamp」、「full」
• days_offset - 今日からの日数（負の値も指定できます）
• return_future_dates - 将来の日付の配列を返します
• future_days - 将来の日付の数（return_future_dates=true の場合）

例：

# Get today's date in ISO format
get_current_time(format="iso")
# Returns: {"date": "2025-11-16", "now": {...}, "travel_dates": {...}}

# Get date 7 days from now with future dates array
get_current_time(days_offset=7, return_future_dates=True, future_days=30)

---

Google 検索

search_google

Google でウェブの検索結果、ナレッジグラフ、アンサーボックスを検索します。

パラメーター：

• q（必須）- 検索クエリ
• location - 地名（例：「New York, NY」）
• gl - 国コード（デフォルト：「us」）
• hl - 言語コード（デフォルト：「en」）
• time_period - 期間フィルター：「last_hour」、「last_day」、「last_week」、「last_month」、「last_year」
• num - 1 ページあたりの検索結果数（デフォルト：「10」）
• safe - セーフサーチ：「off」、「active」

例：

search_google(
    q="Python programming tutorials",
    location="San Francisco, CA",
    time_period="last_month",
    num="20"
)

search_google_videos

動画コンテンツを Google Videos で検索します。

パラメーター： 動画固有のフィルターを除き、search_google と同様です

• q（必須）- 検索クエリ
• time_period - アップロード時期で絞り込みます
• device - 「desktop」または「mobile」

例：

search_google_videos(
    q="machine learning tutorial",
    time_period="last_week",
    num="10"
)

search_google_ai_mode

AI が生成した概要と引用元を含めて検索します。

パラメーター：

• q - 検索クエリ（url が指定されていない場合は必須）
• url - 検索対象の画像 URL
• location - ローカライズされた検索結果の地域

戻り値：

• 引用付きの AI 生成概要
• 構造化されたコンテンツブロック（段落、リスト、表、コード）
• 参照リンク
• ウェブ検索結果

例：

search_google_ai_mode(
    q="How does machine learning work?",
    location="United States"
)

---

Google マップ

search_google_maps

場所、ビジネス、サービスを検索します。

パラメーター：

• query（必須）- 検索クエリ
• location_ll - 緯度・経度の座標（形式：「@lat,lng,zoom」）

例：

search_google_maps(
    query="coffee shops near Central Park",
    location_ll="@40.7829,-73.9654,15z"
)

search_google_maps_place

特定の場所の詳細情報を取得します。

パラメーター：

• place_id（data_id が指定されていない場合は必須）- Google マップの場所 ID
• data_id - 代替の場所識別子
• google_domain - Google のドメイン（デフォルト：「google.com」）
• hl - 言語コード（デフォルト：「en」）

例：

search_google_maps_place(
    place_id="ChIJN1t_tDeuEmsRUsoyG83frY4"
)

search_google_maps_reviews

特定の場所のレビューを取得します。

パラメーター：

• place_id（data_id が指定されていない場合は必須）- Google マップの場所 ID
• data_id - 代替の場所識別子
• sort_by - 「most_relevant」、「newest」、「highest_rating」、「lowest_rating」
• rating - 評価による絞り込み：「1」～「5」

例：

search_google_maps_reviews(
    place_id="ChIJN1t_tDeuEmsRUsoyG83frY4",
    sort_by="newest",
    rating="5"
)

---

Google イベント

search_google_events

イベント、コンサート、カンファレンス、アクティビティを検索します。

パラメーター：

• q（必須）- 検索クエリ（例：「concerts in NYC」、「tech conferences」）
• location - ローカライズされた検索結果の地域名
• chips - 日付フィルター（「today」、「tomorrow」、「week」、「weekend」、「month」）またはイベントの種類
• gl - 国コード（デフォルト：「us」）
• hl - 言語コード（デフォルト：「en」）
• page - ページ番号（デフォルト：「1」）

例：

search_google_events(
    q="music festivals in Austin",
    chips="weekend",
    location="Austin, TX"
)

---

Google フライト

search_google_flights

詳細な条件を指定してフライトを検索します。

パラメーター：

• departure_id（必須）- 空港コード（例：「JFK」）
• arrival_id（必須）- 空港コード（例：「LAX」）
• outbound_date（必須）- 出発日（YYYY-MM-DD）
• flight_type - 「one_way」、「round_trip」、「multi_city」
• return_date - 復路の日付（round_trip の場合は必須）
• travel_class - 「economy」、「premium_economy」、「business」、「first」
• stops - 「0」（直行便）、「1」、「2」
• adults - 大人の人数
• currency - 通貨コード（例：「USD」）

例：

search_google_flights(
    departure_id="JFK",
    arrival_id="LAX",
    outbound_date="2025-12-15",
    return_date="2025-12-22",
    flight_type="round_trip",
    travel_class="economy",
    stops="0",
    adults="2"
)

search_google_flights_calendar

柔軟な日程を計画するための料金カレンダーを取得します。

パラメーター：

• flight_type（必須）- "one_way" または "round_trip"
• departure_id（必須）- 空港コード
• arrival_id（必須）- 空港コード
• outbound_date（必須）- 基準日
• return_date - round_trip の場合は必須

例：

search_google_flights_calendar(
    flight_type="round_trip",
    departure_id="SFO",
    arrival_id="NYC",
    outbound_date="2025-12-01",
    return_date="2025-12-08"
)

search_google_flights_location_search

空港コードと場所を検索します。

パラメーター：

• q（必須）- 検索クエリ（空港名、都市名、またはコード）
• gl - 国コード（デフォルト："us"）
• hl - 言語コード（デフォルト："en"）

例：

search_google_flights_location_search(
    q="Tokyo"
)

search_google_travel_explore

旅行先を探して、アイデアを見つけます。

パラメーター：

• departure_id（必須）- 出発空港コードまたは場所
• arrival_id - 目的地（デフォルトは指定なし）
• time_period - 旅行期間（例："two_week_trip_in_december"）
• interests - 興味で絞り込み："popular"、"outdoors"、"beaches"、"museums"、"history"、"skiing"
• travel_class - "economy"、"premium_economy"、"business"、"first_class"
• adults - 大人の人数（デフォルト："1"）
• currency - 通貨コード（デフォルト："USD"）

例：

search_google_travel_explore(
    departure_id="JFK",
    interests="beaches",
    time_period="two_week_trip_in_december"
)

---

Google ホテル

search_google_hotels

ホテルや宿泊施設を検索します。

パラメーター：

• q（必須）- 場所の検索クエリ
• check_in_date（必須）- チェックイン日（YYYY-MM-DD）
• check_out_date（必須）- チェックアウト日（YYYY-MM-DD）
• adults - 大人の人数（デフォルト："2"）
• rating - 最低評価："3"、"4"、"5"
• hotel_class - 星評価："2"～"5"
• price_min / price_max - 価格帯
• amenities - 設備で絞り込み（例："pool,wifi,parking"）
• free_cancellation - "true" または "false"

例：

search_google_hotels(
    q="hotels in Paris",
    check_in_date="2025-12-20",
    check_out_date="2025-12-25",
    adults="2",
    rating="4",
    amenities="wifi,pool",
    price_max="300",
    free_cancellation="true"
)

search_google_hotels_property

特定のホテルの詳細情報を取得します。

パラメーター：

• property_token（必須）- 検索結果に含まれる施設 ID
• check_in_date（必須）- チェックイン日
• check_out_date（必須）- チェックアウト日
• adults - 大人の人数

例：

search_google_hotels_property(
    property_token="ChIJd8BlQ2BZwokRAFUEcm_qrcA",
    check_in_date="2025-12-20",
    check_out_date="2025-12-25",
    adults="2"
)

---

使用例

例 1：旅行先を見つけて計画する

# 1. Explore destinations from New York
destinations = search_google_travel_explore(
    departure_id="JFK",
    interests="beaches",
    time_period="two_week_trip_in_december"
)

# 2. Get current date and travel dates
dates = get_current_time(return_future_dates=True, future_days=30)
check_in = dates["travel_dates"]["next_week"]
check_out = dates["travel_dates"]["next_month"]

# 3. Search for flights
flights = search_google_flights(
    departure_id="JFK",
    arrival_id="CDG",
    outbound_date=check_in,
    return_date=check_out,
    flight_type="round_trip",
    travel_class="economy",
    adults="2"
)

# 4. Search for hotels
hotels = search_google_hotels(
    q="hotels in Paris",
    check_in_date=check_in,
    check_out_date=check_out,
    adults="2",
    rating="4",
    amenities="wifi,breakfast"
)

# 5. Find nearby restaurants
restaurants = search_google_maps(
    query="restaurants near Eiffel Tower"
)

# 6. Get detailed place info
place_details = search_google_maps_place(
    place_id=restaurants["local_results"][0]["place_id"]
)

# 7. Find local events
events = search_google_events(
    q="concerts in Paris",
    chips="weekend"
)

例 2：AI モードで調査する

# Get AI-generated overview with sources
result = search_google_ai_mode(
    q="What are the health benefits of Mediterranean diet?",
    location="United States"
)

# Result includes:
# - result["markdown"] - AI overview in markdown format
# - result["text_blocks"] - Structured content blocks
# - result["reference_links"] - Cited sources
# - result["web_results"] - Traditional search results

例 3：サービスの健全性を監視する

# Check API health and metrics
health = health_check()

print(f"Status: {health['api_status']['status']}")
print(f"Latency: {health['api_status']['latency_ms']}ms")
print(f"Cache hit rate: {health['metrics']['cache_hit_rate']:.2%}")
print(f"Total requests: {health['metrics']['request_count']}")

---

開発

テストの実行

# Run all tests
python -m pytest

# Run specific test file
python test_refactored.py

コード構成

searchAPI-mcp/
├── mcp_server_refactored.py  # Main MCP server with FastMCP
├── config.py                  # Configuration with Pydantic validation
├── client.py                  # HTTP client with pooling, retry, caching
├── requirements.txt           # Python dependencies
├── .env.example              # Example environment variables
└── tests/                    # Test files

主要コンポーネント

• mcp_server_refactored.py - FastMCP を使用した MCP サーバーの実装

  • 詳細な docstring を含むツール定義
  • ヘルスチェックと監視用エンドポイント
  • クリーンなシャットダウンとリソース管理

• config.py - 設定管理

  • 型安全な設定を実現する Pydantic モデル
  • 環境変数の検証
  • 上書き可能な適切なデフォルト値

• client.py - 本番環境対応の HTTP クライアント

  • httpx による接続プーリング
  • 指数バックオフによる再試行ロジック
  • TTL ベースのレスポンスキャッシュ
  • サーキットブレーカーパターン
  • メトリクス収集

デバッグ

MCP Inspector を使用してツールをテストします。

# Install inspector
npm install -g @modelcontextprotocol/inspector

# Run inspector
npx @modelcontextprotocol/inspector python mcp_server_refactored.py

詳細なログ出力を有効にするには、環境変数を設定します。

LOG_LEVEL=DEBUG python mcp_server_refactored.py

---

トラブルシューティング

よくある問題

問題："Invalid API key" エラー

• 解決策：環境変数または .env ファイルで SEARCHAPI_API_KEY が正しく設定されていることを確認します。
• API キーは https://www.searchapi.io/ で取得できます。

問題："Circuit breaker is OPEN" エラー

• 原因：API 呼び出しが連続して失敗しすぎています。
• 解決策：インターネット接続と API キーを確認します。サーキットがリセットされるまで 60 秒待つか、サーバーを再起動してください。

問題：接続がタイムアウトする

• 解決策：.env でタイムアウトを増やします：TIMEOUT=60.0
• SearchAPI.io へのネットワーク接続を確認します。

問題：レイテンシーが高い

• 解決策：キャッシュが無効の場合は有効にします：ENABLE_CACHE=true
• キャッシュサイズを増やします：CACHE_MAX_SIZE=5000
• health_check ツールでメトリクスを確認します。

問題：Windows のエンコードエラー

• 解決策：MCP クライアントの設定で環境変数を設定します。

  "env": {
    "PYTHONIOENCODING": "utf-8",
    "SEARCHAPI_API_KEY": "your_key"
  }
  

ヘルプ

• MCP ドキュメントを確認してください
• SearchAPI.io ドキュメントを参照してください
• GitHubでイシューを作成してください

---

パフォーマンスの調整

キャッシュの設定

キャッシュヒット率を高めるには：

CACHE_TTL=7200        # 2 hours
CACHE_MAX_SIZE=5000   # Store more results

メモリに制約のある環境では：

CACHE_TTL=1800        # 30 minutes
CACHE_MAX_SIZE=100    # Smaller cache

コネクションプール

トラフィックの多いシナリオでは：

POOL_CONNECTIONS=50
POOL_MAXSIZE=50

トラフィックの少ないシナリオでは：

POOL_CONNECTIONS=5
POOL_MAXSIZE=5

---

セキュリティに関する考慮事項

⚠️ 重要なセキュリティ上の注意：

1. API キーの保護

   • .envファイルをバージョン管理にコミットしないでください
   • 本番環境では環境変数を使用してください
   • API キーを定期的にローテーションしてください

2. レート制限

   • SearchAPI.io には、プランに応じたレート制限があります
   • 組み込みの再試行ロジックはレート制限を遵守します
   • health_checkツールで使用状況を監視してください

3. データプライバシー

   • 検索クエリは SearchAPI.io に送信されます
   • レスポンスはローカルにキャッシュされます（設定可能）
   • SearchAPI.io のプライバシーポリシーを確認してください

---

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細については、LICENSEファイルを参照してください。

---

謝辞

• Model Context Protocol - Anthropic によるプロトコル仕様
• FastMCP - Python MCP フレームワーク
• SearchAPI.io - 検索 API サービスプロバイダー
• httpx - Python 用のモダンな HTTP クライアント
• Pydantic - データ検証フレームワーク

---

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。大規模な変更については、まずイシューを作成して、変更したい内容についてご相談ください。

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

---

変更履歴

v1.1.0（現在）

• ✅ 新機能： Google Maps Place API - 詳細な場所情報
• ✅ 新機能： Google Events API - イベントとアクティビティの検索
• ✅ 新機能： Google Travel Explore API - 目的地の検索
• ✅ 新機能： Google Flights Location Search API - 空港の検索
• ✅ 観光および旅行の調査機能を強化
• ✅ 包括的な旅行計画ワークフローをサポート

v1.0.0

• ✅ FastMCP を使用した本番環境対応アーキテクチャ
• ✅ コネクションプーリングと再試行ロジック
• ✅ TTL によるレスポンスキャッシュ
• ✅ サーキットブレーカーパターン
• ✅ 包括的なヘルスチェックとメトリクス
• ✅ Google 検索、動画、AI モード
• ✅ Google マップとレビュー
• ✅ Google フライトとカレンダー
• ✅ Google ホテルと物件の詳細
• ✅ 旅行計画用の時間ユーティリティ

---