RmMargt/searchAPI-mcp

SearchAPI MCP Server

Features

🔍 Search Engines

• Google Search - Web results, knowledge graph, answer boxes, related questions
• Google Videos - Video search with filtering by duration, source, and upload time
• Google AI Mode - AI-generated overviews with cited sources and structured content
• Google Maps - Places, businesses, reviews, and location details
• Google Maps Place - Detailed information for specific locations (hours, photos, amenities)
• Google Events - Find concerts, conferences, festivals, and local activities
• Google Flights - Flight search with comprehensive filtering and price calendars
• Google Flights Location Search - Airport code lookup and autocomplete
• Google Travel Explore - Discover destinations and travel inspiration
• Google Hotels - Accommodation search with amenities, ratings, and price filters

🏗️ Production-Ready Architecture

• Connection Pooling - Efficient HTTP connection management with httpx
• Response Caching - Configurable TTL-based caching with LRU eviction
• Retry Logic - Exponential backoff for transient failures
• Circuit Breaker - Fail-safe pattern preventing cascading failures
• Metrics Collection - Request counts, latencies, cache hit rates, error tracking
• Health Checks - Monitor API connectivity and service status

⚙️ Configuration & Monitoring

• Pydantic Validation - Type-safe configuration with environment variable support
• Structured Logging - Configurable log levels with detailed request tracing
• Resource Management - Automatic cleanup and graceful shutdown
• Environment Variables - Flexible configuration for different deployments

Quick Start

Prerequisites

• Python 3.10 or higher
• SearchAPI.io API key (Get one here)

Installation with UV (Recommended)

The fastest way to get started is using uvx:

# Set your API key
export SEARCHAPI_API_KEY="your_api_key_here"

# Run directly with uvx (no installation needed)
uvx --from git+https://github.com/RmMargt/searchAPI-mcp.git mcp-server-searchapi

Installation

Method 1: UV (Recommended)

UV is the fastest and most convenient method:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/RmMargt/searchAPI-mcp.git
cd searchAPI-mcp

# Install dependencies
uv pip install -r requirements.txt

Method 2: pip

# Clone the repository
git clone https://github.com/RmMargt/searchAPI-mcp.git
cd searchAPI-mcp

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Method 3: From Source

git clone https://github.com/RmMargt/searchAPI-mcp.git
cd searchAPI-mcp

# Using uv
uv pip install httpx fastmcp python-dotenv pydantic pydantic-settings

# Or using pip
pip install httpx fastmcp python-dotenv pydantic pydantic-settings

Configuration

Environment Variables

Create a .env file in the project root:

# Required
SEARCHAPI_API_KEY=your_api_key_here

# Optional - API Configuration
SEARCHAPI_API_URL=https://www.searchapi.io/api/v1/search
TIMEOUT=30.0
MAX_RETRIES=3
RETRY_BACKOFF=1.0

# Optional - Cache Configuration
ENABLE_CACHE=true
CACHE_TTL=3600
CACHE_MAX_SIZE=1000

# Optional - Connection Pool
POOL_CONNECTIONS=10
POOL_MAXSIZE=10

# Optional - Monitoring
ENABLE_METRICS=true
LOG_LEVEL=INFO

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

Location:

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

Using UV (Recommended):

{
  "mcpServers": {
    "searchapi": {
      "command": "uvx",
      "args": [
        "--directory",
        "/absolute/path/to/searchAPI-mcp",
        "python",
        "mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Using Python directly:

{
  "mcpServers": {
    "searchapi": {
      "command": "python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Using virtual environment:

{
  "mcpServers": {
    "searchapi": {
      "command": "/absolute/path/to/searchAPI-mcp/venv/bin/python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

VS Code (Continue, Cline)

Add to .vscode/mcp.json in your workspace or use the "MCP: Open User Configuration" command:

{
  "servers": {
    "searchapi": {
      "command": "python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

With UV:

{
  "servers": {
    "searchapi": {
      "command": "uvx",
      "args": [
        "--directory",
        "/absolute/path/to/searchAPI-mcp",
        "python",
        "mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Zed Editor

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "searchapi": {
      "command": {
        "path": "python",
        "args": [
          "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
        ],
        "env": {
          "SEARCHAPI_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Cline (VS Code Extension)

In Cline settings, add to MCP Servers:

{
  "mcpServers": {
    "searchapi": {
      "command": "python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Generic MCP Client

For any MCP-compatible client:

# Using stdio transport (default)
python /path/to/searchAPI-mcp/mcp_server_refactored.py

# With environment variable
SEARCHAPI_API_KEY=your_key python mcp_server_refactored.py

Available Tools

Health & Monitoring

health_check

Check the health and performance of the SearchAPI service.

Returns:

• API connectivity status
• Response latency
• Circuit breaker state
• Cache statistics
• Request metrics

Example:

{
  "api_status": {
    "status": "healthy",
    "latency_ms": 145.23,
    "circuit_breaker": "closed"
  },
  "cache_stats": {
    "size": 42,
    "max_size": 1000,
    "ttl": 3600
  },
  "metrics": {
    "request_count": 156,
    "error_count": 2,
    "cache_hit_rate": 0.67
  }
}

Time & Date Utilities

get_current_time

Get current time and travel date suggestions. Essential for flight and hotel bookings.

Parameters:

• format - Date format: "iso", "slash", "chinese", "timestamp", "full"
• days_offset - Days from today (can be negative)
• return_future_dates - Return array of future dates
• future_days - Number of future dates (if return_future_dates=true)

Example:

# Get today's date in ISO format
get_current_time(format="iso")
# Returns: {"date": "2025-11-16", "now": {...}, "travel_dates": {...}}

# Get date 7 days from now with future dates array
get_current_time(days_offset=7, return_future_dates=True, future_days=30)

Google Search

search_google

Search Google for web results, knowledge graphs, and answer boxes.

Parameters:

• q (required) - Search query
• location - Location name (e.g., "New York, NY")
• gl - Country code (default: "us")
• hl - Language code (default: "en")
• time_period - Time filter: "last_hour", "last_day", "last_week", "last_month", "last_year"
• num - Results per page (default: "10")
• safe - Safe search: "off", "active"

Example:

search_google(
    q="Python programming tutorials",
    location="San Francisco, CA",
    time_period="last_month",
    num="20"
)

search_google_videos

Search Google Videos for video content.

Parameters: Similar to search_google with video-specific filters

• q (required) - Search query
• time_period - Filter by upload time
• device - "desktop" or "mobile"

Example:

search_google_videos(
    q="machine learning tutorial",
    time_period="last_week",
    num="10"
)

search_google_ai_mode

Search with AI-generated overviews and cited sources.

Parameters:

• q - Search query (required unless url provided)
• url - Image URL to search
• location - Location for localized results

Returns:

• AI-generated overview with citations
• Structured content blocks (paragraphs, lists, tables, code)
• Reference links
• Web results

Example:

search_google_ai_mode(
    q="How does machine learning work?",
    location="United States"
)

Google Maps

search_google_maps

Search for places, businesses, and services.

Parameters:

• query (required) - Search query
• location_ll - Lat/lng coordinates (format: "@lat,lng,zoom")

Example:

search_google_maps(
    query="coffee shops near Central Park",
    location_ll="@40.7829,-73.9654,15z"
)

search_google_maps_place

Get detailed information for a specific place.

Parameters:

• place_id (required if no data_id) - Google Maps place ID
• data_id - Alternative place identifier
• google_domain - Google domain (default: "google.com")
• hl - Language code (default: "en")

Example:

search_google_maps_place(
    place_id="ChIJN1t_tDeuEmsRUsoyG83frY4"
)

search_google_maps_reviews

Get reviews for a specific place.

Parameters:

• place_id (required if no data_id) - Google Maps place ID
• data_id - Alternative place identifier
• sort_by - "most_relevant", "newest", "highest_rating", "lowest_rating"
• rating - Filter by rating: "1"-"5"

Example:

search_google_maps_reviews(
    place_id="ChIJN1t_tDeuEmsRUsoyG83frY4",
    sort_by="newest",
    rating="5"
)

Google Events

search_google_events

Search for events, concerts, conferences, and activities.

Parameters:

• q (required) - Search query (e.g., "concerts in NYC", "tech conferences")
• location - Location name for localized results
• chips - Date filter ("today", "tomorrow", "week", "weekend", "month") or event type
• gl - Country code (default: "us")
• hl - Language code (default: "en")
• page - Page number (default: "1")

Example:

search_google_events(
    q="music festivals in Austin",
    chips="weekend",
    location="Austin, TX"
)

Google Flights

search_google_flights

Search for flights with comprehensive filtering.

Parameters:

• departure_id (required) - Airport code (e.g., "JFK")
• arrival_id (required) - Airport code (e.g., "LAX")
• outbound_date (required) - Departure date (YYYY-MM-DD)
• flight_type - "one_way", "round_trip", "multi_city"
• return_date - Return date (required for round_trip)
• travel_class - "economy", "premium_economy", "business", "first"
• stops - "0" (nonstop), "1", "2"
• adults - Number of adults
• currency - Currency code (e.g., "USD")

Example:

search_google_flights(
    departure_id="JFK",
    arrival_id="LAX",
    outbound_date="2025-12-15",
    return_date="2025-12-22",
    flight_type="round_trip",
    travel_class="economy",
    stops="0",
    adults="2"
)

search_google_flights_calendar

Get price calendar for flexible date planning.

Parameters:

• flight_type (required) - "one_way" or "round_trip"
• departure_id (required) - Airport code
• arrival_id (required) - Airport code
• outbound_date (required) - Reference date
• return_date - Required for round_trip

Example:

search_google_flights_calendar(
    flight_type="round_trip",
    departure_id="SFO",
    arrival_id="NYC",
    outbound_date="2025-12-01",
    return_date="2025-12-08"
)

search_google_flights_location_search

Search for airport codes and locations.

Parameters:

• q (required) - Search query (airport name, city, or code)
• gl - Country code (default: "us")
• hl - Language code (default: "en")

Example:

search_google_flights_location_search(
    q="Tokyo"
)

search_google_travel_explore

Explore travel destinations and find inspiration.

Parameters:

• departure_id (required) - Departure airport code or location
• arrival_id - Destination (defaults to anywhere)
• time_period - Travel period (e.g., "two_week_trip_in_december")
• interests - Filter by interests: "popular", "outdoors", "beaches", "museums", "history", "skiing"
• travel_class - "economy", "premium_economy", "business", "first_class"
• adults - Number of adults (default: "1")
• currency - Currency code (default: "USD")

Example:

search_google_travel_explore(
    departure_id="JFK",
    interests="beaches",
    time_period="two_week_trip_in_december"
)

Google Hotels

search_google_hotels

Search for hotels and accommodation.

Parameters:

• q (required) - Location query
• check_in_date (required) - Check-in date (YYYY-MM-DD)
• check_out_date (required) - Check-out date (YYYY-MM-DD)
• adults - Number of adults (default: "2")
• rating - Minimum rating: "3", "4", "5"
• hotel_class - Star rating: "2"-"5"
• price_min / price_max - Price range
• amenities - Filter by amenities (e.g., "pool,wifi,parking")
• free_cancellation - "true" or "false"

Example:

search_google_hotels(
    q="hotels in Paris",
    check_in_date="2025-12-20",
    check_out_date="2025-12-25",
    adults="2",
    rating="4",
    amenities="wifi,pool",
    price_max="300",
    free_cancellation="true"
)

search_google_hotels_property

Get detailed information for a specific hotel.

Parameters:

• property_token (required) - Property ID from search results
• check_in_date (required) - Check-in date
• check_out_date (required) - Check-out date
• adults - Number of adults

Example:

search_google_hotels_property(
    property_token="ChIJd8BlQ2BZwokRAFUEcm_qrcA",
    check_in_date="2025-12-20",
    check_out_date="2025-12-25",
    adults="2"
)

Usage Examples

Example 1: Discover and Plan a Trip

# 1. Explore destinations from New York
destinations = search_google_travel_explore(
    departure_id="JFK",
    interests="beaches",
    time_period="two_week_trip_in_december"
)

# 2. Get current date and travel dates
dates = get_current_time(return_future_dates=True, future_days=30)
check_in = dates["travel_dates"]["next_week"]
check_out = dates["travel_dates"]["next_month"]

# 3. Search for flights
flights = search_google_flights(
    departure_id="JFK",
    arrival_id="CDG",
    outbound_date=check_in,
    return_date=check_out,
    flight_type="round_trip",
    travel_class="economy",
    adults="2"
)

# 4. Search for hotels
hotels = search_google_hotels(
    q="hotels in Paris",
    check_in_date=check_in,
    check_out_date=check_out,
    adults="2",
    rating="4",
    amenities="wifi,breakfast"
)

# 5. Find nearby restaurants
restaurants = search_google_maps(
    query="restaurants near Eiffel Tower"
)

# 6. Get detailed place info
place_details = search_google_maps_place(
    place_id=restaurants["local_results"][0]["place_id"]
)

# 7. Find local events
events = search_google_events(
    q="concerts in Paris",
    chips="weekend"
)

Example 2: Research with AI Mode

# Get AI-generated overview with sources
result = search_google_ai_mode(
    q="What are the health benefits of Mediterranean diet?",
    location="United States"
)

# Result includes:
# - result["markdown"] - AI overview in markdown format
# - result["text_blocks"] - Structured content blocks
# - result["reference_links"] - Cited sources
# - result["web_results"] - Traditional search results

Example 3: Monitor Service Health

# Check API health and metrics
health = health_check()

print(f"Status: {health['api_status']['status']}")
print(f"Latency: {health['api_status']['latency_ms']}ms")
print(f"Cache hit rate: {health['metrics']['cache_hit_rate']:.2%}")
print(f"Total requests: {health['metrics']['request_count']}")

Development

Running Tests

# Run all tests
python -m pytest

# Run specific test file
python test_refactored.py

Code Structure

searchAPI-mcp/
├── mcp_server_refactored.py  # Main MCP server with FastMCP
├── config.py                  # Configuration with Pydantic validation
├── client.py                  # HTTP client with pooling, retry, caching
├── requirements.txt           # Python dependencies
├── .env.example              # Example environment variables
└── tests/                    # Test files

Key Components

• mcp_server_refactored.py - MCP server implementation using FastMCP

  • Tool definitions with comprehensive docstrings
  • Health checks and monitoring endpoints
  • Clean shutdown and resource management

• config.py - Configuration management

  • Pydantic models for type-safe configuration
  • Environment variable validation
  • Sensible defaults with override options

• client.py - Production-ready HTTP client

  • Connection pooling with httpx
  • Exponential backoff retry logic
  • TTL-based response caching
  • Circuit breaker pattern
  • Metrics collection

Debugging

Use the MCP Inspector to test tools:

# Install inspector
npm install -g @modelcontextprotocol/inspector

# Run inspector
npx @modelcontextprotocol/inspector python mcp_server_refactored.py

Set environment variable for verbose logging:

LOG_LEVEL=DEBUG python mcp_server_refactored.py

Troubleshooting

Common Issues

Issue: "Invalid API key" error

• Solution: Ensure SEARCHAPI_API_KEY is set correctly in environment or .env file
• Get an API key at https://www.searchapi.io/

Issue: "Circuit breaker is OPEN" error

• Cause: Too many consecutive API failures
• Solution: Check your internet connection and API key. Wait 60 seconds for circuit to reset, or restart the server

Issue: Connection timeouts

• Solution: Increase timeout in .env: TIMEOUT=60.0
• Check network connectivity to SearchAPI.io

Issue: High latency

• Solution: Enable caching if disabled: ENABLE_CACHE=true
• Increase cache size: CACHE_MAX_SIZE=5000
• Check health_check tool for metrics

Issue: Windows encoding errors

• Solution: Set environment variable in your MCP client config:

  "env": {
    "PYTHONIOENCODING": "utf-8",
    "SEARCHAPI_API_KEY": "your_key"
  }
  

Getting Help

• Check the MCP Documentation
• Review SearchAPI.io Documentation
• Open an issue on GitHub

Performance Tuning

Cache Configuration

For higher cache hit rates:

CACHE_TTL=7200        # 2 hours
CACHE_MAX_SIZE=5000   # Store more results

For memory-constrained environments:

CACHE_TTL=1800        # 30 minutes
CACHE_MAX_SIZE=100    # Smaller cache

Connection Pool

For high-traffic scenarios:

POOL_CONNECTIONS=50
POOL_MAXSIZE=50

For low-traffic scenarios:

POOL_CONNECTIONS=5
POOL_MAXSIZE=5

Security Considerations

⚠️ Important Security Notes:

1. API Key Protection

   • Never commit .env file to version control
   • Use environment variables in production
   • Rotate API keys regularly

2. Rate Limiting

   • SearchAPI.io has rate limits based on your plan
   • Built-in retry logic respects rate limits
   • Monitor usage with health_check tool

3. Data Privacy

   • Search queries are sent to SearchAPI.io
   • Responses are cached locally (configurable)
   • Review SearchAPI.io privacy policy

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• Model Context Protocol - Protocol specification by Anthropic
• FastMCP - Python MCP framework
• SearchAPI.io - Search API service provider
• httpx - Modern HTTP client for Python
• Pydantic - Data validation framework

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Changelog

v1.1.0 (Current)

• ✅ New: Google Maps Place API - Detailed place information
• ✅ New: Google Events API - Event and activity search
• ✅ New: Google Travel Explore API - Destination discovery
• ✅ New: Google Flights Location Search API - Airport lookup
• ✅ Enhanced tourism and travel research capabilities
• ✅ Comprehensive travel planning workflow support

v1.0.0

• ✅ Production-ready architecture with FastMCP
• ✅ Connection pooling and retry logic
• ✅ Response caching with TTL
• ✅ Circuit breaker pattern
• ✅ Comprehensive health checks and metrics
• ✅ Google Search, Videos, AI Mode
• ✅ Google Maps and Reviews
• ✅ Google Flights and Calendar
• ✅ Google Hotels and Property details
• ✅ Time utilities for travel planning