SerpApi MCP Server

Exposes SerpApi's Google Search endpoint through the Model Context Protocol (MCP), allowing LLM agents to execute web searches by sending structured search queries and receiving parsed SERP results. Implements MCP's tool-calling interface to translate natural language search intents into SerpApi HTTP requests, handling parameter serialization, API authentication via API key, and response parsing into structured JSON containing organic results, knowledge panels, and metadata.

Transforms raw SerpApi JSON responses into normalized, structured output suitable for LLM consumption. Extracts and flattens nested result objects (organic results, knowledge panels, answer boxes, related searches) into consistent field schemas with standardized field names, types, and null-handling. Implements response filtering to surface only relevant fields (title, link, snippet, position) while discarding SerpApi metadata, reducing token consumption in LLM context windows.

Provides a schema-based interface for constructing SerpApi search queries with parameter validation and type coercion. Accepts parameters like query string, location, language, number of results, and search type (web/news/images) through MCP tool arguments, validates against SerpApi's supported parameter ranges and enums, and constructs properly-formatted HTTP query strings. Implements sensible defaults (e.g., num_results=10) and parameter constraints (e.g., max 100 results per request) to prevent invalid API calls.

Registers SerpApi search capabilities as discoverable MCP tools with standardized tool schemas (name, description, input schema). Implements MCP's tool discovery protocol, allowing MCP clients (Claude Desktop, custom hosts) to enumerate available tools, inspect their parameters and descriptions, and invoke them with type-safe argument passing. Uses JSON Schema to define tool input parameters (query, location, language, num_results) with descriptions, types, and constraints, enabling clients to provide autocomplete and validation UI.

Manages SerpApi authentication by accepting and securely storing API keys, injecting them into outbound SerpApi requests as query parameters or headers. Implements environment variable loading (e.g., SERPAPI_API_KEY) to avoid hardcoding credentials in code or configuration files. Validates API key format before making requests and provides clear error messages when authentication fails (invalid key, quota exceeded, rate limited).

Implements error handling for SerpApi HTTP failures (4xx/5xx responses, network timeouts, rate limiting) by catching exceptions, parsing error responses, and returning human-readable error messages to the LLM. Distinguishes between client errors (invalid parameters, authentication failure) and server errors (SerpApi outage, rate limit exceeded), providing context-specific guidance. Implements exponential backoff retry logic for transient failures (5xx, timeouts) with configurable retry counts and delays.

Logs all SerpApi requests and responses (query, parameters, result count, latency, status code) to enable debugging and monitoring. Implements structured logging (JSON format) with timestamps, request IDs, and error details, allowing integration with observability platforms (CloudWatch, Datadog, ELK). Provides metrics on API usage (requests per minute, average latency, error rates) for quota tracking and performance optimization.