Google Search MCP Server
This server lets MCP-compatible AI agents (like Claude, Cursor, Cline) perform live web searches via a single tool.
Search the web using the
search_googletool, which takes aquerystring (e.g.,"latest TypeScript release").Get top 3 results for each query, including title, link, and snippet.
Integrate with any MCP client over stdio — just point your client config to the built
build/index.jsor run via Docker.Use in your own projects — build your own MCP agent and call the tool programmatically via the MCP SDK.
Handle missing results gracefully — returns
"No results found."if nothing matches.
Provides web search through Google Custom Search, returning top results with titles, links, and snippets.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Google Search MCP Server Search Google for the latest developments in AI this week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🔍 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 ( |
🔧 Google Custom Search Setup
Create a project in the Google Cloud Console
Enable the
Custom Search APIfor that projectGenerate an API key
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 installCreate a .env file in the project root:
GOOGLE_API_KEY=your_google_api_key
SEARCH_ENGINE_ID=your_search_engine_id⚠️ Never commit
.envor expose your API key in source control.
▶️ Run
Development (run TypeScript directly):
npm startProduction (build then run compiled output):
npm run build
node build/index.jsℹ️ The server logs status and errors to
stderr, keepingstdoutclean 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
-iflag 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:
- .envdocker compose up --buildPoint 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:
Clone and build this repo (or pull the Docker image — see Run with Docker).
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.Supported clients — any tool that speaks MCP over stdio works, including:
Calling it programmatically — if you're building your own MCP client/agent in code, connect an MCP
ClientoverStdioClientTransportpointed atbuild/index.js, then call thesearch_googletool 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.jsMake 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?
Fork the repo
Create a branch (
git checkout -b feature/your-feature)Make your changes and test locally (
npm startordocker compose up --build)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
Available Tools
1 toolsearch_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
Scored across 1 tool
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.
The tool name follows a clear verb_noun pattern (search_google), which is consistent and descriptive. There are no other tools to create inconsistencies.
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.
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
Related MCP Connectors
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
Search Google straight from your AI agent. Web results, images, videos, news, products, scholarly ar
Web search API and MCP server for developers building AI agents.
Free web search for AI agents. No API key required. Hosted MCP in active development.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables users to perform Google Custom Search queries through the Model Context Protocol. Requires Google API credentials and Custom Search Engine configuration for web search functionality.1MIT
- AlicenseBqualityDmaintenanceEnables Large Language Models to perform real-time web searches using Google Custom Search API. Integrates with Claude Desktop to retrieve current information from the internet.21MIT
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to perform real-time Google searches and retrieve web results via the MCP protocol.-
- AlicenseDqualityDmaintenanceEnables Google web search via MCP, compatible with gemini-cli's google_web_search tool.222 npmApache 2.0