hands-on-mcp-with-python

Google Custom Search API を利用した簡易 MCP サーバー例です。server_google_search.py で google_search ツールを提供します。

セットアップ

1. 依存インストール (uv / pip など任意の方法)
2. .env に API キーと CSE ID を設定

GOOGLE_CSE_API_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
GOOGLE_CSE_ID=aaaaaaaaaaaaaaaaa_bbccccccccc

Google Programmable Search Engine (旧 Custom Search Engine) で「検索エンジン」を作成し、cx 値を GOOGLE_CSE_ID に設定してください。

実行

MCP サーバーとして実行

uv run python server_google_search.py

サーバーは stdio 経由で MCP プロトコルを使用します。Claude Desktop や他の MCP クライアントから接続できます。

Claude Desktop での設定例

~/Library/Application Support/Claude/claude_desktop_config.json に追加:

{
  "mcpServers": {
    "google_search": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/hands-on-mcp-with-python",
        "run",
        "python",
        "server_google_search.py"
      ],
      "env": {
        "GOOGLE_CSE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_cse_id_here"
      }
    }
  }
}

返却フォーマット

最大 5 件の検索結果を次の形式で返します:

1. <タイトル>
<URL>
<スニペット>

2. <タイトル>
...

結果が 0 件の場合は 検索結果は0件でした。 を返します。

API キー未設定時は設定方法を促すメッセージを返します。

エラーハンドリング

以下のエラー状況に対応しています:

• 環境変数未設定: GOOGLE_CSE_API_KEY または GOOGLE_CSE_ID が未設定の場合
• 入力バリデーション: 空クエリ、2048文字を超える長いクエリ
• HTTP エラー:
  • 400: リクエスト不正
  • 401: API認証エラー
  • 403: アクセス権限エラー (APIキーまたはCSE_ID不正)
  • 429: API利用制限超過
  • 500/503: Google API サーバーエラー
• ネットワークエラー: タイムアウト、接続エラー
• レスポンス形式エラー: 予期しないAPI応答形式

ロギング

MCP の Context を通じてクライアントにログを送信します:

• INFO: 検索実行、結果件数
• WARNING: 入力バリデーションエラー
• ERROR: API エラー、環境変数未設定
• DEBUG: API レスポンス詳細

ログは ctx.info(), ctx.warning(), ctx.error(), ctx.debug() を使用して MCP クライアント（Claude Desktop など）に送信されます。

ライセンス

MIT (必要に応じて変更してください)