Google Search MCP Server

🔍 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

• ✨ Overview

• ⚙️ Requirements

• 🔧 Google Custom Search Setup

• ⚠️ Rate Limits & Quota

• 📦 Installation

• ▶️ Run

• 🐳 Run with Docker

  • Point your MCP client to Docker

• 🔌 MCP Client Configuration

• 🧩 Using This Server in Your Own Project

• 🛠️ Available Tool

  • search_google

• 🧪 Test with MCP Inspector

• 📁 Project Structure

• 🤝 Contributing

• 📄 License

• 👤 Author

Related MCP server: Google Search MCP

✨ 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

🔧 Google Custom Search Setup

1. Create a project in the Google Cloud Console

2. Enable the Custom Search API for that project

3. Generate an API key

4. Create a Programmable Search Engine 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 under APIs & Services → Custom Search API → Quotas.

📦 Installation

npm install

Create a .env file in the project root:

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

npm start

Production (build then run compiled output):

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:

docker build -t google-search-mcp .

Run it (make sure your .env file is set up first — see Installation):

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:

services:
  google-search-mcp:
    build: .
    stdin_open: true
    tty: true
    env_file:
      - .env

docker compose up --build

Point your MCP client to Docker

{
  "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:

{
  "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:

{
  "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).

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.

3. Supported clients — any tool that speaks MCP over stdio works, including:

   • Claude Desktop

   • Cursor (.cursor/mcp.json)

   • Cline (VS Code extension settings)

   • Custom agents built with the MCP SDK 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 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

{
  "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

npm run build
npx @modelcontextprotocol/inspector node build/index.js

Make sure your environment variables are set before launching the inspector.

📁 Project Structure

📦 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 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.

👤 Author

M. Hasindu Udara Full-Stack Developer