SearchAPI MCP Server

A production-ready Model Context Protocol (MCP) server providing comprehensive search capabilities through SearchAPI.io. Enable AI assistants to search Google, Maps, Flights, Hotels, and more with built-in caching, retry logic, and circuit breakers.

一个基于 Model Context Protocol (MCP) 的生产级搜索服务器，通过 SearchAPI.io 提供全面的搜索功能。使 AI 助手能够搜索 Google、地图、航班、酒店等，内置缓存、重试逻辑和熔断器。

Features • Quick Start • Installation • Configuration • Available Tools

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:

API Key Protection
- Never commit .env file to version control
- Use environment variables in production
- Rotate API keys regularly
Rate Limiting
- SearchAPI.io has rate limits based on your plan
- Built-in retry logic respects rate limits
- Monitor usage with health_check tool
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 LICENSE 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.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
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

⬆ Back to Top

Made with ❤️ for the MCP community

SearchAPI MCP Server

Features • Quick Start • Installation • Configuration • Available Tools

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:

API Key Protection
- Never commit .env file to version control
- Use environment variables in production
- Rotate API keys regularly
Rate Limiting
- SearchAPI.io has rate limits based on your plan
- Built-in retry logic respects rate limits
- Monitor usage with health_check tool
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 LICENSE 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.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
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

⬆ Back to Top

Made with ❤️ for the MCP community