Version 4.2.0 - Enhanced research synthesis with intelligent source quality assessment and deduplication, powered by SerpAPI.

An advanced Model Context Protocol (MCP) server that provides comprehensive Google search capabilities via SerpAPI, webpage content extraction, and AI-powered research synthesis. Built for Claude Code, Claude Desktop, and other MCP-compatible clients.

Note: This is the serpapi-only branch - a standalone version focused exclusively on SerpAPI as the search provider. This branch will remain separate from the multi-provider main branch and provides a simpler, streamlined experience with SerpAPI.

This server uses SerpAPI to provide reliable Google search results through a simple, well-maintained API.

• Simple Setup - Only one API key needed (no complex Google Cloud configuration)
• Reliable - Not being sunset like Google's official Custom Search API
• Good Free Tier - 100 searches/month for development and testing
• Affordable - $50/month for 5,000 searches ($0.01 per search)
• Better Documentation - Clear API docs and helpful error messages
• More Features - Easy access to Google Images, News, Videos, etc.

Get your API key at: https://serpapi.com/manage-api-key

This MCP server transforms Google search into a powerful research tool by:

• Intelligent Source Ranking - Automatically scores sources by authority, recency, and credibility
• Deduplication - Removes duplicate URLs and similar content across search results
• Agent-Based Synthesis - Leverages your existing Claude session to synthesize research findings
• Focus Area Analysis - Provides dedicated analysis for specific aspects of your research topic
• Quality Metrics - Tracks source diversity, authority, and content freshness

• Node.js 18 or higher
• SerpAPI account (free tier available)

Run directly without cloning:

# Set environment variable and run
SERPAPI_KEY=your_key npx google-search-mcp

Or create a .env file in your working directory:

SERPAPI_KEY=your_serpapi_key_here

Then run:

npx google-search-mcp

# Clone the repository
git clone https://github.com/mixelpixx/Google-Search-MCP-Server
cd Google-Search-MCP-Server

# Install dependencies
npm install

# Build the project
npm run build

Create a .env file in the project root:

# Required: Your SerpAPI key
SERPAPI_KEY=your_serpapi_key_here

# Optional: Usage tracking
USAGE_TRACKING_ENABLED=true
USAGE_TRACKING_PERSIST=true
USAGE_MAX_SEARCHES_PER_MONTH=100
USAGE_MAX_COST_PER_MONTH=10.00

Get your API key: https://serpapi.com/manage-api-key

Note: No Anthropic API key is required. The server uses agent-based synthesis that leverages your existing Claude session.

Track your API usage and costs to prevent unexpected bills:

# Enable usage tracking
USAGE_TRACKING_ENABLED=true

# Persist tracking to SQLite database (optional)
USAGE_TRACKING_PERSIST=true
USAGE_TRACKING_DB_PATH=./.mcp-usage-tracking.db

# Set thresholds for warnings (optional)
USAGE_MAX_SEARCHES_PER_MONTH=100  # Alert at 80% and 100%
USAGE_MAX_COST_PER_MONTH=10.00    # In USD

Benefits:

• Monitor usage in real-time
• Get warnings at 80% and 100% of limits
• Prevent quota overruns
• Track estimated costs
• Historical data with SQLite persistence

# Start v3 server (recommended)
npm run start:v3

# For HTTP mode
npm run start:v3:http

Expected output:

Validating SerpAPI credentials...
SerpAPI credentials validated successfully

============================================================
Google Search MCP Server v4.2.0 (SerpAPI)
============================================================
Using SerpAPI as search provider
  Free tier: 100 searches/month
Source quality assessment
Deduplication
AI synthesis: AGENT MODE (Claude will launch agents)
  No API key needed - uses your existing Claude session
Focus area analysis
Enhanced error handling
Cache metadata
============================================================
Server running on STDIO

With usage tracking enabled:

Using SerpAPI as search provider
Usage tracking enabled
Usage tracking database initialized: ./.mcp-usage-tracking.db

• Full-text search with quality scoring
• Domain filtering and date restrictions
• Result categorization (academic, official docs, news, forums, etc.)
• Automatic deduplication of results
• Source authority ranking
• Support for images, news, and video search

• Clean content extraction from web pages
• Multiple output formats (Markdown, HTML, plain text)
• Configurable preview lengths
• Batch extraction support (up to 5 URLs)
• Automatic content summarization

• Agent-based research analysis
• Comprehensive source synthesis
• Focus area breakdowns
• Contradiction detection
• Actionable recommendations
• Quality metrics reporting

research_topic({
  topic: "WebAssembly performance optimization",
  depth: "basic"
})

Returns:

• 3 high-quality sources
• Brief overview (2-3 paragraphs)
• 3-5 key findings
• Quality metrics

research_topic({
  topic: "Kubernetes security",
  depth: "advanced",
  focus_areas: ["RBAC", "network policies", "pod security"],
  num_sources: 8
})

Returns:

• 8 authoritative sources
• In-depth executive summary
• 7-10 detailed findings
• Common themes across sources
• Dedicated analysis for each focus area
• Contradictions between sources
• Actionable recommendations
• Comprehensive quality metrics

google_search({
  query: "docker container security best practices",
  num_results: 10,
  dateRestrict: "y1",  // Last year only
  site: "github.com"   // Limit to GitHub
})

Returns:

• Quality-scored results
• Duplicate removal report
• Source type classification
• Authority ratings

extract_webpage_content({
  url: "https://kubernetes.io/docs/concepts/security/",
  format: "markdown",
  max_length: 5000,
  preview_length: 300
})

Returns:

• Clean extracted content
• Metadata (title, description, author)
• Word count and statistics
• Configurable preview
• Cache information

Agent Mode is the default synthesis method. Instead of requiring a separate Anthropic API key, it uses your existing Claude session:

1. Research Gathering - MCP server searches, deduplicates, and ranks sources
2. Content Extraction - Full content extracted from top sources
3. Agent Prompt Generation - All research data packaged into structured prompt
4. Agent Launch - Claude Code automatically launches agent with research data
5. Synthesis - Agent analyzes sources and generates comprehensive report

• No Additional API Key - Uses your existing Claude subscription
• Full Context - Agent has access to conversation history
• Transparent Process - See agent analysis in real-time
• Same Quality - Uses same Claude model you're already using

For automated workflows or scripts, you can use Direct API mode:

# .env
ANTHROPIC_API_KEY=your_anthropic_api_key
USE_DIRECT_API=true

This bypasses agent mode and calls the Anthropic API directly from the MCP server.

src/
├── google-search-v3.ts              # Main MCP server (v3)
├── services/
│   ├── providers/
│   │   ├── serpapi-provider.ts      # SerpAPI integration
│   │   ├── base-provider.ts         # Provider interface
│   │   └── provider-factory.ts      # Provider creation
│   ├── google-search.service.ts     # Search service layer
│   ├── content-extractor.service.ts # Web content extraction
│   ├── source-quality.service.ts    # Source ranking and scoring
│   ├── deduplication.service.ts     # Duplicate detection
│   └── research-synthesis.service.ts # Agent-based synthesis
└── types.ts                          # TypeScript interfaces

Search Query → SerpAPI → Results
                            ↓
                       Deduplication
                            ↓
                       Quality Scoring
                            ↓
                       Content Extraction
                            ↓
                       Agent Synthesis
                            ↓
                  Comprehensive Research Report

Search Google with advanced filtering and quality scoring.

Parameters:

• query (string, required) - Search query
• num_results (number, optional) - Number of results (default: 5, max: 10)
• site (string, optional) - Limit to specific domain
• language (string, optional) - ISO 639-1 language code
• dateRestrict (string, optional) - Date filter (e.g., "m6" for last 6 months)
• exactTerms (string, optional) - Exact phrase matching
• resultType (string, optional) - Filter by type (image, news, video)
• page (number, optional) - Pagination
• sort (string, optional) - Sort by relevance or date

Returns:

• Ranked search results with quality scores
• Deduplication statistics
• Source categorization
• Pagination info
• Cache metadata

Extract clean content from a webpage.

Parameters:

• url (string, required) - Target URL
• format (enum, optional) - Output format: markdown, html, text (default: markdown)
• full_content (boolean, optional) - Return full content (default: false)
• max_length (number, optional) - Maximum content length
• preview_length (number, optional) - Preview length (default: 500)

Returns:

• Extracted content
• Metadata (title, description, author)
• Statistics (word count, character count)
• Content summary
• Cache information

Batch extract content from multiple URLs (max 5).

Parameters:

• urls (array, required) - Array of URLs (max 5)
• format (enum, optional) - Output format

Returns:

• Extracted content per URL
• Error details for failed extractions
• Cache metadata

Comprehensive research with AI synthesis.

Parameters:

• topic (string, required) - Research topic
• depth (enum, optional) - Analysis depth: basic, intermediate, advanced (default: intermediate)
• num_sources (number, optional) - Number of sources (default: varies by depth)
• focus_areas (array, optional) - Specific aspects to analyze

Returns:

• Executive summary
• Key findings with citations
• Common themes
• Focus area analysis (if specified)
• Contradictions between sources
• Recommendations
• Quality metrics (source diversity, authority, freshness)
• Source list with quality scores

Symptoms: "Invalid SerpAPI Key" or "Access Denied" errors

Solutions:

1. Check SERPAPI_KEY is correct in your .env file
2. Verify your key at: https://serpapi.com/manage-api-key
3. Make sure there are no extra spaces when copying the key
4. Ensure the key hasn't been revoked or expired

Symptoms: "Rate Limit Exceeded" or "Quota exceeded" errors

Solutions:

1. You exceeded 100 searches this month (free tier)
2. Wait until next month for quota reset
3. Or upgrade your plan: https://serpapi.com/pricing
4. Monitor usage: https://serpapi.com/account

Symptoms: "Cannot Reach SerpAPI" or connection timeouts

Solutions:

1. Check your internet connection
2. Verify firewall/proxy settings allow connections to serpapi.com
3. Check SerpAPI status: https://status.serpapi.com/

Symptoms: Research returns basic concatenation instead of synthesis

Solutions:

1. Verify server shows "AGENT MODE" on startup
2. Check for [AGENT_SYNTHESIS_REQUIRED] in response
3. Ensure using v3: npm run start:v3
4. Rebuild: npm run build

Symptoms: Search results don't show quality scores

Solutions:

1. Confirm running v3, not v2
2. Check server startup output for errors
3. Verify no TypeScript compilation errors
4. Rebuild the project: npm run build

• QUICK-START.md - Fast setup guide (2 minutes)
• AGENT-MODE.md - Comprehensive agent mode documentation
• SERPAPI-MIGRATION-GUIDE.md - Migration guide from other providers

• SerpAPI Integration - Reliable Google search via SerpAPI as sole provider
• Simplified Architecture - Single provider for easier maintenance
• Agent-based synthesis - No API key required for synthesis
• Source quality assessment - Automatic ranking by authority and relevance
• Comprehensive deduplication - Remove duplicate and similar content
• Focus area analysis - Dedicated analysis for specific topics
• Enhanced error handling - Helpful suggestions for common issues
• Usage tracking - Monitor searches and costs
• Cache metadata - Transparency for cached results
• Research depth levels - Basic, intermediate, and advanced research modes

• Multi-provider support (Google, Brave, Tavily)
• Provider factory pattern
• Usage tracking across providers

• HTTP transport support
• Batch webpage extraction
• Basic research synthesis
• Content categorization

• Initial release
• Google Custom Search integration
• Basic content extraction

Contributions are welcome! Please ensure:

1. Code follows existing style conventions
2. All tests pass: npm run build
3. Documentation is updated
4. Commit messages are descriptive

See LICENSE file for details.

For issues, questions, or feature requests, please open an issue on GitHub.

• SerpAPI - Google search API provider
• Anthropic Claude - AI-powered research synthesis
• Mozilla Readability - Content extraction
• MCP SDK - Model Context Protocol integration

Version: 4.2.0 (serpapi-only branch) Last Updated: 2026-01-31