🔍 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

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

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