mcp-native web search via google custom search api
Exposes a single 'search' tool through the Model Context Protocol that forwards queries to Google's Custom Search API with structured parameter validation. The server implements the MCP tool definition schema with comprehensive input validation (query string, pagination, language restrictions, safety filtering) and returns JSON-formatted search results. Uses stdio transport for client-server communication, allowing MCP clients (Claude Desktop, Cline, VS Code Copilot) to invoke searches without direct API integration.
Unique: Implements MCP protocol as a lightweight bridge to Google Custom Search API, enabling zero-configuration search tool injection into MCP clients via npx command-line invocation with environment-based credential passing, rather than requiring client-side SDK installation or persistent service deployment.
vs alternatives: Simpler than building custom search integrations in each MCP client because it standardizes search as a reusable MCP server; more flexible than hardcoded search in Claude because it supports language restrictions, pagination, and safe search filtering through schema-validated parameters.
parameterized search query construction with validation
Implements a comprehensive input schema (defined in src/index.ts lines 34-65) that validates and structures search parameters before forwarding to Google's API. The schema enforces type constraints (string for query, integer for page/size), range validation (size 1-10), enum constraints (sort: 'date' only), and optional language restriction codes. Parameter validation occurs in the CallToolRequestSchema handler, preventing malformed requests from reaching the Google API and reducing quota waste.
Unique: Uses MCP's native tool input schema validation (JSON Schema) to enforce parameter constraints at the protocol level before API calls, preventing invalid requests from consuming quota; supports language restriction and safe search as first-class parameters rather than post-processing filters.
vs alternatives: More robust than client-side validation because constraints are enforced at the MCP server boundary; cleaner than REST API wrappers because schema validation is declarative in the tool definition rather than imperative in request handlers.
google custom search api request translation and forwarding
Translates MCP tool invocations into properly formatted HTTP requests to Google's Custom Search API endpoints. The CallToolRequestSchema handler (src/index.ts lines 67-157) constructs query parameters, handles authentication via API key, and supports two endpoint modes: standard Google Custom Search API (https://www.googleapis.com/customsearch) and site-restricted variants. Responses are parsed from Google's JSON format and reformatted into MCP-compliant structured results with title, link, and snippet fields.
Unique: Implements endpoint abstraction that allows switching between standard and site-restricted Google Custom Search API modes via boolean parameter (siteRestricted), enabling single MCP server to serve multiple search engine configurations without redeployment.
vs alternatives: Simpler than building separate MCP servers for each search mode because endpoint selection is parameterized; more maintainable than direct API clients in each MCP consumer because credential and endpoint logic is centralized in the server.
mcp protocol server lifecycle and tool registration
Implements the MCP Server class from the MCP SDK with metadata configuration and tool capability declaration. The server initializes with name, version, and capabilities metadata (src/index.ts lines 20-31), registers a single 'search' tool with its input schema, and implements two request handlers: ListToolsRequestSchema (returns tool definitions) and CallToolRequestSchema (executes search requests). Uses stdio transport for bidirectional communication with MCP clients, allowing clients to discover available tools and invoke them with type-safe parameters.
Unique: Uses MCP SDK's Server class to handle protocol boilerplate (message serialization, request routing, error handling) rather than implementing MCP protocol manually, reducing server code to ~150 lines while maintaining full protocol compliance.
vs alternatives: Cleaner than custom JSON-RPC servers because MCP SDK handles transport and serialization; more discoverable than REST APIs because tool schemas are advertised through ListTools before invocation, enabling client-side validation and UI generation.
on-demand server instantiation via npx with environment-based configuration
Enables MCP clients to launch the google-pse-mcp server on-demand using 'npx -y google-pse-mcp' with command-line arguments for API credentials and endpoint configuration. The server reads arguments in order: API endpoint URL, API key, and Custom Search Engine ID (cx). This pattern eliminates persistent service deployment and allows clients to inject credentials at runtime without modifying configuration files. The server process lifecycle is tied to the client connection — it terminates when the client disconnects.
Unique: Uses npx for zero-installation deployment, allowing MCP clients to launch the server without npm install or persistent service management; credentials are passed as command-line arguments rather than environment variables or config files, enabling per-invocation credential injection.
vs alternatives: Simpler than Docker-based MCP servers because no container runtime is required; more flexible than hardcoded credentials because API key and endpoint are parameterized at launch time; faster than managed services because server starts on-demand rather than running continuously.
pagination support with page number and result size parameters
Implements pagination through two parameters: 'page' (page number, default 1) and 'size' (results per page, 1-10, default 10). The server translates these into Google Custom Search API's 'start' parameter (calculated as (page - 1) * size + 1) and 'num' parameter. This abstraction provides a familiar pagination interface (page/size) while mapping to Google's 1-indexed 'start' offset model. Clients can iterate through result sets by incrementing the page parameter without calculating offsets manually.
Unique: Abstracts Google Custom Search API's 1-indexed 'start' offset model into familiar page/size parameters, calculating start = (page - 1) * size + 1 internally; provides default pagination (page 1, 10 results) without requiring explicit parameters.
vs alternatives: More intuitive than raw offset-based pagination because page numbers are human-readable; more efficient than fetching all results at once because clients can control batch size and stop after finding relevant results.
language restriction filtering via language codes
Supports the 'lr' (language restriction) parameter that filters search results to specific languages using Google's language code format (e.g., 'lang_en' for English, 'lang_es' for Spanish). The parameter is passed directly to Google Custom Search API's 'lr' query parameter. This enables agents to restrict searches to specific languages without post-processing results, reducing irrelevant results and API quota consumption for multilingual applications.
Unique: Exposes Google Custom Search API's language restriction codes as a first-class parameter in the MCP tool schema, enabling agents to specify language filters without API documentation lookup; passed directly to Google API without transformation.
vs alternatives: More efficient than post-processing results by language because filtering occurs at the API level; more flexible than hardcoded language restrictions because language can be parameterized per query.
safe search filtering toggle
Implements a boolean 'safe' parameter that enables Google's safe search filtering, which removes adult content and other potentially inappropriate results. When set to true, the parameter is passed to Google Custom Search API's 'safe' query parameter. This provides a simple on/off toggle for content filtering without requiring agents to implement custom content moderation logic.
Unique: Provides simple boolean toggle for Google's safe search filtering without requiring agents to implement custom content moderation; passed directly to Google API as 'safe' parameter.
vs alternatives: Simpler than building custom content filters because filtering is delegated to Google's infrastructure; more reliable than client-side filtering because it operates on full page content before snippet extraction.
+1 more capabilities