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:

A Google Cloud Project with Custom Search API enabled
- Visit Google Cloud Console
- Enable the Custom Search API
- Create API credentials
A Custom Search Engine ID
- Visit Programmable Search Engine
- Create a new search engine
- Get your Search Engine ID
Local development requirements:
- Node.js (v18 or higher)
- npm (comes with Node.js)

🚀 Quick Start

Clone the repository:

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

Install dependencies:
```
npm install
```

Create a .env file:

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

Build the server:
```
npm run build
```
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

Using MCP Inspector:

npx @modelcontextprotocol/inspector node build/index.js

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