Incorporo/valueserp-googlesearch-mcp

🔍 ValueSerp MCP Server

🌟 What This Does

Transform Claude AI into a powerful search engine with real-time access to Google's vast knowledge base. This MCP server enables Claude to perform live Google searches, browse news, discover images, and find videos - all without leaving the conversation.

✨ Key Highlights

• 🔍 Live Google Search - Real-time web, news, image, and video search
• 🖼️ Smart Image Processing - Automatic base64 image detection and native display
• 📊 CSV Output Support - Structured data extraction with 50+ field options
• 🌍 Global Localization - Search in any language, country, or region
• ⚡ High Performance - Built with TypeScript, comprehensive error handling
• 🔒 Production Ready - Extensive test coverage and security best practices

🛠️ Features

🖼️ Revolutionary Image Processing

Our advanced image processing system automatically detects and converts base64 images in API responses to native MCP image resources, providing a seamless visual experience in Claude.

Features:

• ✅ Automatic base64 detection (PNG, JPEG, GIF, WebP, SVG)
• ✅ MIME type recognition and validation
• ✅ Size optimization (1MB limit compliance)
• ✅ Circular reference handling
• ✅ User-controllable with process_images parameter

🚀 Quick Start

Prerequisites

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

git clone

Installation

Easiest: Use the published npm package (recommended)

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

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

Check version:

valueserp-mcp --version  # prints 1.0.0

Set your API key (required):

export VALUESERP_API_KEY="your_api_key_here"

Then run (if installed globally):

valueserp-mcp

Manual (clone & build)

# 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 Setup

Add to your Claude Desktop configuration:

📁 Config Location:

• 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"
      }
    }
  }
}

📦 Published Package

The server is published to npm as @incorporo/valueserp-mcp.

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

Verify from your environment:

npm view @incorporo/valueserp-mcp version

Upgrade to the latest version anytime:

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

Or run on-demand without global install:

npx @incorporo/valueserp-mcp

🗒️ Changelog

1.0.0

• Initial public release on npm
• CLI executable (valueserp-mcp) with stdio transport
• Search tools: web, news, images, videos, places, place details
• Automatic base64 image extraction to MCP image blocks

📖 Usage Guide

Basic Web Search

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

News Search with Sorting

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

Image Search with Processing

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

Video Discovery

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

Places & Local Business Search

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

Place Details Lookup

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

⚙️ Configuration Options

📊 CSV Fields & Data Structure

Rich Data Extraction

Each search type supports extensive CSV field extraction for structured data processing:

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

🧪 Testing & Quality

Comprehensive Test Suite

# Run all tests
npm test

# Run with coverage
npm run test:coverage

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

Test Coverage:

• ✅ 56 tests passing across unit and integration suites
• ✅ 6 search tools - Web, News, Images, Videos, Places, and Place Details
• ✅ Image processing - 24 comprehensive tests
• ✅ API validation - Parameter validation and error handling
• ✅ Integration testing - Real-world scenario validation

Code Quality

• 🔍 TypeScript - Full type safety and IntelliSense
• 🛡️ Error Handling - Graceful failure recovery
• 📝 Documentation - Comprehensive inline documentation
• 🔒 Security - No hardcoded secrets, input validation

🎯 Advanced Features

🖼️ Base64 Image Processing

Revolutionary feature that automatically detects base64 images in API responses and converts them to native MCP image resources.

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

How it works:

1. 🔍 Detection - Scans API responses for base64 image data
2. 🔄 Conversion - Converts to MCP-compatible image blocks
3. 🖼️ Display - Images render natively in Claude interface
4. ⚡ Optimization - Respects 1MB size limits for performance

🌍 Global Localization

Search in any language, country, or region with precise targeting:

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

🚨 Error Handling

The server provides comprehensive error handling:

• 🔍 Parameter Validation - Clear error messages for invalid inputs
• 🌐 Network Resilience - Automatic retry logic and timeout handling
• 🔑 API Error Translation - Human-readable ValueSerp API error messages
• 🛡️ Security - Input sanitization and rate limiting awareness

📚 Resources

🤝 Contributing

We welcome contributions! Here's how to get started:

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

# Run tests
npm test

# Build
npm run build

📄 License

This project is licensed under the GNU General Public License v3.0 - see the file for details.

GPL v3 ensures this software remains free and open source. Any derivative works must also be licensed under GPL v3, preserving the freedom for all users to run, study, share, and modify the software.