Valueserp Mcp - Affordable Google Searches

🔍 ValueSerp MCP サーバー

🌟 これは何をするものですか

Google の膨大なナレッジベースにリアルタイムでアクセスできる強力な検索エンジンへと、Claude AI を変身させます。この MCP サーバーを使うと、会話から離れることなく、Claude が Google でライブ検索を行い、ニュースを閲覧し、画像を見つけ、動画を探せるようになります。

✨ 主な特長

• 🔍 Google ライブ検索 - ウェブ、ニュース、画像、動画をリアルタイムで検索
• 🖼️ スマートな画像処理 - base64 画像を自動検出し、ネイティブ形式で表示
• 📊 CSV 出力に対応 - 50 以上のフィールドオプションを使った構造化データの抽出
• 🌍 グローバルなローカライズ - 任意の言語、国、地域で検索
• ⚡ 高パフォーマンス - TypeScript で構築され、包括的なエラー処理を備えています
• 🔒 本番環境に対応 - 広範なテストカバレッジとセキュリティのベストプラクティスを採用

🛠️ 機能

🖼️ 画期的な画像処理

高度な画像処理システムが API のレスポンス内の base64 画像を自動で検出し、ネイティブ MCP 画像リソースに変換するため、Claude でシームレスに画像を表示できます。

機能：

• ✅ base64 を自動検出（PNG、JPEG、GIF、WebP、SVG）
• ✅ MIME タイプの認識と検証
• ✅ サイズの最適化（1MB の上限に準拠）
• ✅ 循環参照の処理
• ✅ process_images パラメーターでユーザーが制御可能

🚀 クイックスタート

前提条件

# Required
Node.js 18+
ValueSerp API Key (get free at valueserp.com)

git clone

インストール

最も簡単な方法：公開済み npm パッケージを使用（推奨）

# Install globally
npm install -g @incorporo/valueserp-mcp

# OR run directly without installing
npx @incorporo/valueserp-mcp

バージョンを確認します：

valueserp-mcp --version  # prints 1.0.0

API キーを設定します（必須）：

export VALUESERP_API_KEY="your_api_key_here"

続いて実行します（グローバルにインストールした場合）：

valueserp-mcp

手動（クローンしてビルド）

# 1. Clone the repository
git clone <repository-url>
cd valueserp-mcp

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Set your API key
export VALUESERP_API_KEY="your_api_key_here"

# 5. Start the server
npm start

Claude Desktop のセットアップ

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

📁 設定ファイルの場所：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "valueserp": {
      "command": "valueserp-mcp",
      "env": {
        "VALUESERP_API_KEY": "your_api_key_here"
      }
    }
  }
}

📦 公開パッケージ

サーバーは npm で @incorporo/valueserp-mcp として公開されています。

name:     @incorporo/valueserp-mcp
version:  1.0.0
files:    dist/*.js + types, README, LICENSE
size:     ~33 kB (compressed)

環境から確認します：

npm view @incorporo/valueserp-mcp version

いつでも最新バージョンにアップグレードできます：

npm install -g @incorporo/valueserp-mcp@latest

または、グローバルにインストールせず、必要に応じて実行します：

npx @incorporo/valueserp-mcp

🗒️ 変更履歴

1.0.0

• npm での初回公開リリース
• stdio トランスポート対応の CLI 実行ファイル（valueserp-mcp）
• 検索ツール：ウェブ、ニュース、画像、動画、場所、場所の詳細
• base64 画像を MCP 画像ブロックに自動抽出

📖 使用ガイド

基本的なウェブ検索

{
  "tool": "google_search",
  "parameters": {
    "q": "latest AI developments 2025",
    "location": "United States",
    "num": 10,
    "time_period": "last_week",
    "include_ai_overview": true
  }
}

並べ替えを指定したニュース検索

{
  "tool": "google_news_search", 
  "parameters": {
    "q": "climate change",
    "sort_by": "date",
    "location": "United Kingdom",
    "num": 15,
    "time_period": "last_day"
  }
}

画像処理を伴う画像検索

{
  "tool": "google_images_search",
  "parameters": {
    "q": "modern architecture",
    "images_size": "large",
    "images_color": "any",
    "process_images": true,
    "num": 20
  }
}

動画の検索

{
  "tool": "google_videos_search",
  "parameters": {
    "q": "TypeScript tutorials",
    "time_period": "last_month",
    "safe": "active",
    "num": 10
  }
}

場所と地域のビジネスの検索

{
  "tool": "google_places_search",
  "parameters": {
    "q": "coffee shops",
    "location": "San Francisco, CA",
    "num": 20,
    "process_images": true
  }
}

場所の詳細情報の照会

{
  "tool": "google_place_details",
  "parameters": {
    "data_id": "0x87b7122bd8e99a89:0xf20c18461109b2c0",
    "hl": "en",
    "process_images": true
  }
}

⚙️ 設定オプション

📊 CSV フィールドとデータ構造

豊富なデータ抽出

各検索タイプでは、構造化データ処理のために幅広い CSV フィールドの抽出に対応しています：

organic_results.position, organic_results.title, organic_results.link, 
organic_results.snippet, organic_results.displayed_link, 
search_information.total_results, related_questions.question, 
knowledge_graph.title, local_results.title, local_results.address

news_results.position, news_results.title, news_results.source,
news_results.date, news_results.link, news_results.snippet,
news_results.thumbnail, search_information.total_results

image_results.position, image_results.title, image_results.width,
image_results.height, image_results.image, image_results.link,
image_results.source.name, image_results.description

video_results.position, video_results.title, video_results.link,
video_results.length, video_results.source, video_results.date,
video_results.snippet, search_information.total_results

places_results.position, places_results.title, places_results.address,
places_results.phone, places_results.rating, places_results.reviews,
places_results.category, places_results.gps_coordinates.latitude,
places_results.gps_coordinates.longitude, local_results.title,
local_results.address, local_results.rating, local_results.reviews

place_details.title, place_details.type, place_details.address,
place_details.phone, place_details.website, place_details.rating,
place_details.reviews, place_details.description, place_details.hours,
place_details.gps_coordinates.latitude, place_details.gps_coordinates.longitude

🧪 テストと品質

包括的なテストスイート

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suites
npm test tests/unit/
npm test tests/integration/

テストカバレッジ：

• ✅ 56 件のテストに合格（ユニットテストおよび統合テストスイート）
• ✅ 6 つの検索ツール — ウェブ、ニュース、画像、動画、場所、場所の詳細
• ✅ 画像処理 — 包括的なテスト 24 件
• ✅ API 検証 — パラメーターの検証とエラー処理
• ✅ 統合テスト — 実際のシナリオの検証

コード品質

• 🔍 TypeScript — 完全な型安全性と IntelliSense
• 🛡️ エラー処理 — 障害発生時の適切な復旧
• 📝 ドキュメント — 詳細なインラインドキュメント
• 🔒 セキュリティ — ハードコードされたシークレットなし、入力検証あり

🎯 高度な機能

🖼️ Base64 画像処理

API レスポンス内の Base64 画像を自動的に検出し、ネイティブの MCP 画像リソースに変換する画期的な機能です。

{
  "tool": "google_images_search",
  "parameters": {
    "q": "cats",
    "process_images": true    // Enable automatic image processing
  }
}

仕組み：

1. 🔍 検出 — API レスポンスをスキャンし、Base64 画像データを検出します
2. 🔄 変換 — MCP 互換の画像ブロックに変換します
3. 🖼️ 表示 — 画像は Claude のインターフェースにネイティブ表示されます
4. ⚡ 最適化 — パフォーマンスを維持するため、サイズ制限の 1 MB を遵守します

🌍 グローバルローカライズ

対象を正確に指定して、あらゆる言語、国、地域で検索できます。

{
  "location": "Tokyo, Japan",
  "gl": "jp",
  "hl": "ja",
  "google_domain": "google.co.jp"
}

🚨 エラー処理

サーバーは包括的なエラー処理を提供します。

• 🔍 パラメーター検証 — 無効な入力に対して明確なエラーメッセージを表示します
• 🌐 ネットワークの耐障害性 — 自動再試行ロジックとタイムアウト処理
• 🔑 API エラーの変換 — ValueSerp API のエラーメッセージを人が読みやすい形式に変換します
• 🛡️ セキュリティ — 入力のサニタイズとレート制限への対応

📚 リソース

🤝 コントリビューション

コントリビューションを歓迎します。始めるには、以下をご覧ください。

# Development setup
git clone <repo-url>
cd valueserp-mcp
npm install
npm run dev

# Run tests
npm test

# Build
npm run build

📄 ライセンス

このプロジェクトは GNU General Public License v3.0 のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。

GPL v3 により、このソフトウェアは自由でオープンソースのまま維持されます。派生物にも GPL v3 のライセンスを適用する必要があり、すべてのユーザーがソフトウェアを実行、調査、共有、変更できる自由が保たれます。