📌Overview

Purpose: To provide web search capabilities for Language Learning Models (LLMs) using Google's Custom Search API through a standardized Model Context Protocol (MCP) interface.

Overview: The MCP Google Custom Search Server allows seamless integration with Google's Custom Search API, enabling LLMs to perform web searches efficiently. This server is designed with a type-safe implementation in TypeScript, ensuring robust and reliable performance for users.

Key Features:

• Seamless Integration: Directly connects with the Google Custom Search API, facilitating web search functionality.

• MCP Compliance: Implements the Model Context Protocol, ensuring compatibility with various MCP clients, including Claude Desktop.

• Type Safety: Built using TypeScript, enhancing code reliability and minimizing runtime errors.

• Configurable Results: Supports customization of search results, allowing retrieval of up to 10 results per query, complete with titles, URLs, and descriptions.

• Input Validation: Utilizes Zod for thorough input validation, reinforcing the integrity of search requests and responses.

• Error Handling: Includes comprehensive error handling mechanisms to manage issues elegantly during web searches.

---

MCP Google Custom Search Server

A Model Context Protocol (MCP) server providing web search capabilities through Google's Custom Search API. This server enables Language Learning Models (LLMs) to perform web searches using a standardized interface.

Features

• Seamless integration with Google Custom Search API
• MCP-compliant server implementation
• Type-safe implementation using TypeScript
• Environment variable configuration
• Input validation using Zod
• Configurable search results (up to 10 per query)
• Formatted search results including titles, URLs, and descriptions
• Error handling and validation
• Compatible with Claude Desktop and other MCP clients

Prerequisites

Ensure you have:

1. A Google Cloud Project with Custom Search API enabled

   • Enable the Custom Search API in Google Cloud Console
   • Create API credentials

2. A Custom Search Engine ID

   • Create a new search engine at Programmable Search Engine
   • Obtain your Search Engine ID

3. Local development requirements:

   • Node.js (v18 or higher)
   • npm (comes with Node.js)

Quick Start

1. Clone the repository:

   git clone https://github.com/yourusername/mcp-google-custom-search-server.git
   cd mcp-google-custom-search-server
   

2. Install dependencies:

   npm install
   

3. Create a .env file with the following:

   GOOGLE_API_KEY=your-api-key
   GOOGLE_SEARCH_ENGINE_ID=your-search-engine-id
   

4. Build the server:

   npm run build
   

5. Start the server:

   npm start
   

Configuration

Environment Variables

Variable	Description	Required
GOOGLE_API_KEY	Your Google Custom Search API key	Yes
GOOGLE_SEARCH_ENGINE_ID	Your Custom Search Engine ID	Yes

Claude Desktop Integration

Add this configuration to your Claude Desktop config file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "google-search": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-google-custom-search-server/build/index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your-api-key",
        "GOOGLE_SEARCH_ENGINE_ID": "your-search-engine-id"
      }
    }
  }
}

API Reference

Available Tools

search

Performs a web search using Google Custom Search API.

Parameters:

• query (string, required): The search query to execute
• numResults (number, optional): Number of results to return
  • Default: 5
  • Maximum: 10

Example Response:

Result 1:
Title: Example Search Result
URL: https://example.com
Description: This is an example search result description
---

Result 2:
...

Development

Project Structure

mcp-google-custom-search-server/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── .env                  # Environment variables
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md             # Project documentation

Available Scripts

• npm run build: Compile TypeScript to JavaScript
• npm start: Start the MCP server
• npm run dev: Watch mode for development

Testing

1. Using MCP Inspector:

   npx @modelcontextprotocol/inspector node build/index.js
   

2. Manual testing with example queries:

   # After starting the server
   {"jsonrpc":"2.0","id":1,"method":"callTool","params":{"name":"search","arguments":{"query":"example search"}}}
   

License

This project is licensed under the MIT License.

Acknowledgments

• Built with Model Context Protocol (MCP)
• Uses Google's Custom Search API
• Inspired by the need for better search capabilities in LLM applications