MCP Google Custom Search Server

A Model Context Protocol (MCP) server that provides 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

• Model Context Protocol (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

Before you begin, ensure you have:

1. A Google Cloud Project with Custom Search API enabled

   • Visit Google Cloud Console

   • Enable the Custom Search API

   • Create API credentials

2. A Custom Search Engine ID

   • Visit Programmable Search Engine

   • Create a new search engine

   • Get 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:

   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

Claude Desktop Integration

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

📖 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:

🛠️ Development

Project Structure

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 - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Model Context Protocol (MCP)

• Uses Google's Custom Search API

• Inspired by the need for better search capabilities in LLM applications