Skip to main content
Glama
Google Search MCP Server

Google Search MCP Server

by hasinduudara

Node.js TypeScript MCP Google Custom Search License

Listed on mcpservers.org

🔍 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


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

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.


Listed on mcpservers.org

👤 Author

M. Hasindu Udara Full-Stack Developer

LinkedIn

Available Tools

1 tool
search_googleB

Search the web using Google Custom Search API to find the latest information.

Inputs: query (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of confusion or overlap between tools. The single tool's purpose is clear and distinct by default.

    Naming Consistency5/5

    The tool name follows a clear verb_noun pattern (search_google), which is consistent and descriptive. There are no other tools to create inconsistencies.

    Tool Count3/5

    The server has only one tool, which feels thin for typical MCP servers. However, for a narrowly scoped Google Search service, a single focused search tool is defensible.

    Completeness5/5

    The tool fully covers the stated purpose of searching the web via Google Custom Search API. There are no obvious missing operations for a server dedicated solely to performing web searches.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers