SearchAPI

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

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

# 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

# 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

# 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

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

# 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

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

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

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

Add to.vscode/mcp.jsonin 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" } } } }

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

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

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

# 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

Check the health and performance of the SearchAPI service.

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

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

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

- 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)

# 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)

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

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

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

Parameters:Similar tosearch_googlewith video-specific filters

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

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

Search with AI-generated overviews and cited sources.

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

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

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

Search for places, businesses, and services.

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

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

Get detailed information for a specific place.

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

search_google_maps_place( place_id="ChIJN1t_tDeuEmsRUsoyG83frY4" )

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

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

Search for events, concerts, conferences, and activities.

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

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

Search for flights with comprehensive filtering.

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

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

Get price calendar for flexible date planning.

- 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

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

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

search_google_flights_location_search( q="Tokyo" )

Explore travel destinations and find inspiration.

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

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

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

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

Get detailed information for a specific hotel.

- 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

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

# 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" )

# 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

# 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']}")

# Run all tests python -m pytest # Run specific test file python test_refactored.py

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

-

mcp_server_refactored.py- MCP server implementation using FastMCP

- Tool definitions with comprehensive docstrings
- Health checks and monitoring endpoints
- Clean shutdown and resource 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

# Install inspector npm install -g @modelcontextprotocol/inspector # Run inspector npx @modelcontextprotocol/inspector python mcp_server_refactored.py