Google Search

🔍 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

---

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

---