🔍 ValueSerp MCP Server

Real-time Google Search Integration for Claude AI

Powered by ValueSerp API • Built with Model Context Protocol

🌟 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

🔍 Search Tools

• google_search - Web search with AI overviews
• google_news_search - Latest news with sorting
• google_images_search - Visual search with filters
• google_videos_search - Video discovery
• google_places_search - Local business and place discovery
• google_place_details - Detailed information about specific places

🎯 Advanced Capabilities

• Base64 Image Processing - Automatic image extraction
• Comprehensive CSV Fields - 50+ structured data fields
• Geographic Targeting - Location-based results
• Time Filtering - Recent, custom date ranges
• Safe Search - Content filtering options

🖼️ 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

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

📖 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

Common Parameters (All Tools)

| Parameter | Type | Description | Example | |-----------|------|-------------|---------| | q | string | Required. Search query | "machine learning" | | location | string | Geographic location | "New York, NY" | | gl | string | Country code | "us" | | hl | string | Language code | "en" | | num | number | Results per page (1-100) | 10 | | page | number | Page number | 1 | | safe | string | Safe search (active/off) | "active" | | time_period | string | Time filter | "last_week" | | process_images | boolean | Enable image processing | true |

News-Specific Parameters

| Parameter | Type | Description | |-----------|------|-------------| | sort_by | string | Sort by relevance or date | | show_duplicates | boolean | Show duplicate articles |

Image-Specific Parameters

| Parameter | Type | Options | |-----------|------|---------| | images_color | string | any, black_and_white, transparent, red, blue, etc. | | images_size | string | large, medium, icon | | images_type | string | clipart, line_drawing, gif | | images_usage | string | Usage rights filter |

Places-Specific Parameters

| Parameter | Type | Description | |-----------|------|-------------| | location | string | Geographic location for places search. Text location name or lat:lon coordinates | | num | number | Number of places results per page (maximum 20) | | order_online | boolean | Returns pickup/delivery info for restaurants (costs 2 credits) | | nfpr | number | Exclude auto-corrected results (1) or include (0) |

Place Details Parameters

| Parameter | Type | Description | |-----------|------|-------------| | data_id | string | Google Places data ID for detailed info (more profile data) | | data_cid | string | Google Maps data CID for basic info (limited profile) | | hl | string | Language code for UI language (default: en) |

Note: Either data_id OR data_cid must be provided (mutually exclusive)

📊 CSV Fields & Data Structure

Rich Data Extraction

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

Web Search Fields

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 Search Fields

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 Search Fields

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 Search Fields

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 Search Fields

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 Fields

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

| Resource | Description | |----------|-------------| | 📖 Implementation Guide | Detailed setup and usage tutorial | | 🔧 ValueSerp API Docs | Complete API reference | | 🏗️ MCP Protocol | Model Context Protocol specification | | 💡 Get API Key | Free ValueSerp API access |

🤝 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 LICENSE 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.

Made with ❤️ for the Claude AI community

Bringing real-time search capabilities to conversational AI