searchAPI-mcp

# SearchAPI MCP Server <div align="center"> [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://github.com/jlowin/fastmcp) 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](#features) • [Quick Start](#quick-start) • [Installation](#installation) • [Configuration](#configuration) • [Available Tools](#available-tools) </div> --- ## 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](https://www.searchapi.io/)) ### Installation with UV (Recommended) The fastest way to get started is using `uvx`: ```bash # 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: ```bash # 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 ```bash # 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 ```bash 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: ```bash # 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):** ```json { "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:** ```json { "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:** ```json { "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: ```json { "servers": { "searchapi": { "command": "python", "args": [ "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py" ], "env": { "SEARCHAPI_API_KEY": "your_api_key_here" } } } } ``` **With UV:** ```json { "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`: ```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: ```json { "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: ```bash # 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:** ```json { "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:** ```python # 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:** ```python 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:** ```python 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:** ```python 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:** ```python 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:** ```python 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:** ```python 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:** ```python 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:** ```python 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:** ```python 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:** ```python 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:** ```python 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:** ```python 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:** ```python 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 ```python # 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 ```python # 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 ```python # 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 ```bash # 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: ```bash # Install inspector npm install -g @modelcontextprotocol/inspector # Run inspector npx @modelcontextprotocol/inspector python mcp_server_refactored.py ``` Set environment variable for verbose logging: ```bash 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: ```json "env": { "PYTHONIOENCODING": "utf-8", "SEARCHAPI_API_KEY": "your_key" } ``` ### Getting Help - Check the [MCP Documentation](https://modelcontextprotocol.io/) - Review [SearchAPI.io Documentation](https://www.searchapi.io/docs) - Open an issue on [GitHub](https://github.com/RmMargt/searchAPI-mcp/issues) --- ## Performance Tuning ### Cache Configuration For higher cache hit rates: ```bash CACHE_TTL=7200 # 2 hours CACHE_MAX_SIZE=5000 # Store more results ``` For memory-constrained environments: ```bash CACHE_TTL=1800 # 30 minutes CACHE_MAX_SIZE=100 # Smaller cache ``` ### Connection Pool For high-traffic scenarios: ```bash POOL_CONNECTIONS=50 POOL_MAXSIZE=50 ``` For low-traffic scenarios: ```bash 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 [LICENSE](LICENSE) file for details. --- ## Acknowledgments - **[Model Context Protocol](https://modelcontextprotocol.io/)** - Protocol specification by Anthropic - **[FastMCP](https://github.com/jlowin/fastmcp)** - Python MCP framework - **[SearchAPI.io](https://www.searchapi.io/)** - Search API service provider - **[httpx](https://www.python-httpx.org/)** - Modern HTTP client for Python - **[Pydantic](https://docs.pydantic.dev/)** - 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 --- <div align="center"> **[⬆ Back to Top](#searchapi-mcp-server)** Made with ❤️ for the MCP community </div>