[](https://nodejs.org/) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io/) [](https://programmablesearchengine.google.com/) [](https://opensource.org/licenses/MIT)
[](https://mcpservers.org/servers/hasinduudara/google-search-mcp.git)
### ๐ An MCP server that lets any MCP-compatible AI client search the live web through Google's Custom Search JSON API โ over stdio, plug-and-play.
---
## ๐งญ Table of Contents
- [๐งญ Table of Contents](#-table-of-contents)
- [โจ Overview](#-overview)
- [โ๏ธ Requirements](#๏ธ-requirements)
- [๐ง Google Custom Search Setup](#-google-custom-search-setup)
- [โ ๏ธ Rate Limits \& Quota](#๏ธ-rate-limits--quota)
- [๐ฆ Installation](#-installation)
- [โถ๏ธ Run](#๏ธ-run)
- [๐ณ Run with Docker](#-run-with-docker)
- [Point your MCP client to Docker](#point-your-mcp-client-to-docker)
- [๐ MCP Client Configuration](#-mcp-client-configuration)
- [๐งฉ Using This Server in Your Own Project](#-using-this-server-in-your-own-project)
- [๐ ๏ธ Available Tool](#๏ธ-available-tool)
- [`search_google`](#search_google)
- [๐งช Test with MCP Inspector](#-test-with-mcp-inspector)
- [๐ Project Structure](#-project-structure)
- [๐ค Contributing](#-contributing)
- [๐ License](#-license)
- [๐ค Author](#-author)
---
## โจ Overview
> This server bridges the gap between **AI agents** and **real-time web knowledge**.
> It speaks the **Model Context Protocol (MCP)** over stdio, so any compatible client can call a single tool โ `search_google` โ and get back clean, structured search results straight from Google.
```
โโโโโโโโโโโโโโโโโโโ stdio (MCP) โโโโโโโโโโโโโโโโโโโโโโโโ HTTPS โโโโโโโโโโโโโโโโโโโโโ
โ MCP Client โ โโโโโโโโโโโโโโโโโโโโโโโโถ โ Google Search MCP โ โโโโโโโโโโโโโโโโโโโถ โ Google Custom โ
โ (Claude, etc.) โ โโโโโโโโโโโโโโโโโโโโโโโโ โ Server โ โโโโโโโโโโโโโโโโโโโ โ Search JSON API โ
โโโโโโโโโโโโโโโโโโโ results โโโโโโโโโโโโโโโโโโโโโโโโ results โโโโโโโโโโโโโโโโโโโโโ
```
---
## โ๏ธ Requirements
| Requirement | Details |
|---|---|
| ๐ข **Node.js** | v18 or newer |
| ๐ **Google API Key** | With access to the Custom Search JSON API |
| ๐ **Search Engine ID** | From a Google Programmable Search Engine (`cx`) |
---
## ๐ง Google Custom Search Setup
1. **Create a project** in the [Google Cloud Console](https://console.cloud.google.com/)
2. **Enable** the `Custom Search API` for that project
3. **Generate** an API key
4. **Create** a [Programmable Search Engine](https://programmablesearchengine.google.com/) and copy its **Search Engine ID**
---
## โ ๏ธ Rate Limits & Quota
The Google Custom Search JSON API's **free tier allows 100 queries per day**. Once that limit is hit, the API returns a `429` error and `search_google` will respond with an error message instead of results.
- Need more? You can enable billing on your Google Cloud project for up to 10,000 queries/day (paid, per-query pricing).
- Check your current usage in the [Google Cloud Console](https://console.cloud.google.com/) under **APIs & Services โ Custom Search API โ Quotas**.
---
## ๐ฆ Installation
```bash
npm install
```
Create a `.env` file in the project root:
```env
GOOGLE_API_KEY=your_google_api_key
SEARCH_ENGINE_ID=your_search_engine_id
```
> โ ๏ธ **Never commit `.env`** or expose your API key in source control.
---
## โถ๏ธ Run
**Development** (run TypeScript directly):
```bash
npm start
```
**Production** (build then run compiled output):
```bash
npm run build
node build/index.js
```
> โน๏ธ The server logs status and errors to `stderr`, keeping `stdout` clean for MCP protocol messages.
---
## ๐ณ Run with Docker
Prefer containers? You can build and run this server without installing Node.js locally.
**Build the image:**
```bash
docker build -t google-search-mcp .
```
**Run it** (make sure your `.env` file is set up first โ see [Installation](#-installation)):
```bash
docker run -i --rm --env-file .env google-search-mcp
```
> โ ๏ธ The `-i` flag is required โ this is a stdio-based MCP server and needs an interactive stream to communicate with the client.
**Or use Docker Compose:**
```yaml
services:
google-search-mcp:
build: .
stdin_open: true
tty: true
env_file:
- .env
```
```bash
docker compose up --build
```
### Point your MCP client to Docker
```json
{
"mcpServers": {
"google-search": {
"command": "docker",
"args": ["run", "-i", "--rm", "--env-file", ".env", "google-search-mcp"]
}
}
}
```
## ๐ MCP Client Configuration
After building the project, register the server with an MCP-compatible client using the compiled entry point:
```json
{
"mcpServers": {
"google-search": {
"command": "node",
"args": ["/absolute/path/to/Google-Search-MCP/build/index.js"],
"env": {
"GOOGLE_API_KEY": "your_google_api_key",
"SEARCH_ENGINE_ID": "your_search_engine_id"
}
}
}
}
```
Or keep credentials in the project's `.env` and launch from the project directory:
```json
{
"mcpServers": {
"google-search": {
"command": "node",
"args": ["/absolute/path/to/Google-Search-MCP/build/index.js"]
}
}
}
```
---
## ๐งฉ Using This Server in Your Own Project
This server isn't tied to any single client โ any MCP-compatible host can spawn it and call `search_google`. To use it elsewhere:
1. **Clone and build** this repo (or pull the Docker image โ see [Run with Docker](#-run-with-docker)).
2. **Point your MCP client's config** at the built entry point (`build/index.js`) or the Docker command, using the same JSON shown in [MCP Client Configuration](#-mcp-client-configuration).
3. **Supported clients** โ any tool that speaks MCP over stdio works, including:
- Claude Desktop
- [Cursor](https://www.cursor.com/) (`.cursor/mcp.json`)
- [Cline](https://github.com/cline/cline) (VS Code extension settings)
- Custom agents built with the [MCP SDK](https://modelcontextprotocol.io/) directly
4. **Calling it programmatically** โ if you're building your own MCP client/agent in code, connect an MCP `Client` over `StdioClientTransport` pointed at `build/index.js`, then call the `search_google` tool like any other MCP tool. See the [MCP TypeScript SDK docs](https://modelcontextprotocol.io/) for client-side examples.
> Each client has its own config file location and format for `mcpServers` โ check that client's docs for exactly where to paste the JSON block.
---
## ๐ ๏ธ Available Tool
### `search_google`
Searches Google Custom Search for the supplied query and returns the **top 3 results**.
**Input**
```json
{
"query": "latest TypeScript release"
}
```
**Output**
Each result includes:
- ๐ `title`
- ๐ `link`
- ๐ `snippet`
If nothing is found, the tool responds with `No results found.`
---
## ๐งช Test with MCP Inspector
```bash
npm run build
npx @modelcontextprotocol/inspector node build/index.js
```
> Make sure your environment variables are set before launching the inspector.
---
## ๐ Project Structure
```text
๐ฆ Google-Search-MCP
โโโ ๐ src
โ โโโ index.ts # MCP server implementation
โโโ ๐ build # Compiled JavaScript and type declarations
โโโ .env # Local environment config (not committed)
โโโ README.md
```
---
## ๐ค Contributing
Contributions, bug reports, and feature requests are welcome!
- **Found a bug or have an idea?** [Open an issue](../../issues) describing it.
- **Want to contribute code?**
1. Fork the repo
2. Create a branch (`git checkout -b feature/your-feature`)
3. Make your changes and test locally (`npm start` or `docker compose up --build`)
4. Commit and push, then open a Pull Request
Please keep PRs focused โ one feature or fix per PR makes review easier.
---
## ๐ License
This project is licensed under the [MIT License](LICENSE).
---
**M. Hasindu Udara**
Full-Stack Developer
[](https://www.linkedin.com/in/hasindu-udara)