Skip to main content
Glama
enesjakozh
hunter-arton

Google Search MCP Server

by hunter-arton
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Google Search MCP Server

A Model Context Protocol (MCP) server that provides web and image search capabilities through Google's Custom Search API. This server follows the MCP specification to integrate with Claude and other AI assistants.

What We're Building

Many AI assistants don't have up-to-date information or the ability to search the web. This MCP server solves that problem by providing two tools:

  • google_web_search: Search the web for current information

  • google_image_search: Find images related to queries

Once connected to an MCP-compatible client (like Claude in Cursor, VSCode, or Claude Desktop), your AI assistant can perform searches and access current information.

Related MCP server: Google Search MCP Server

Core MCP Concepts

MCP servers provide capabilities to AI assistants. This server implements:

  • Tools: Functions that can be called by the AI (with user approval)

  • Structured Communication: Standardized messaging format via the MCP protocol

  • Transport Layer: Communication via standard input/output

Prerequisites

  • Node.js (v18 or higher) and npm

  • Google Cloud Platform account

  • Google Custom Search API key and Search Engine ID

  • An MCP-compatible client (Claude for Desktop, Cursor, VSCode with Claude, etc.)

Quick Start (Clone this Repository)

If you want to use this server without building it from scratch, follow these steps:

# Clone the repository
git clone https://github.com/yourusername/google-search-mcp-server.git
cd google-search-mcp-server

# Install dependencies
npm install

# Set up your environment variables
# Setup .env file in the root folder of the project

# On macOS/Linux
touch .env

# On Windows
new-item .env

# Edit .env file to add your Google API credentials
# Use any text editor you prefer (VS Code, Notepad, nano, vim, etc.)
# Add these to your newly created .env

GOOGLE_API_KEY=your_api_key_here
GOOGLE_CSE_ID=your_search_engine_id_here

# Build the server
npm run build

# Test the server (optional)
# On macOS/Linux
echo '{"jsonrpc":"2.0","method":"listTools","id":1}' | node dist/index.js

# On Windows PowerShell
echo '{"jsonrpc":"2.0","method":"listTools","id":1}' | node dist/index.js

# On Windows CMD
echo {"jsonrpc":"2.0","method":"listTools","id":1} | node dist/index.js

After building, follow the Connecting to MCP Clients section to connect the server to your preferred client.

Set Up Your Environment (Build from Scratch)

If you prefer to build the server yourself from scratch, follow these instructions:

Create Project Structure

macOS/Linux

# Create a new directory for our project
mkdir google-search-mcp
cd google-search-mcp

# Initialize a new npm project
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk dotenv zod
npm install -D @types/node typescript

# Create our files
mkdir src
touch src/index.ts

Windows

# Create a new directory for our project
md google-search-mcp
cd google-search-mcp

# Initialize a new npm project
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk dotenv zod
npm install -D @types/node typescript

# Create our files
md src
new-item src\index.ts

Configure TypeScript

Create a tsconfig.json in the root directory:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Update package.json

Ensure your package.json includes:

{
  "name": "google_search_mcp",
  "version": "0.1.0",
  "description": "MCP server for Google Custom Search API integration",
  "license": "MIT",
  "type": "module",
  "bin": {
    "google_search": "./dist/index.js"
  },
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "tsc",
    "build:unix": "tsc && chmod 755 dist/index.js",
    "prepare": "npm run build",
    "watch": "tsc --watch",
    "start": "node dist/index.js"
  }
}

Google API Setup

You'll need to set up Google Cloud Platform and get API credentials:

Google Cloud Platform Setup

  1. Go to Google Cloud Console

  2. Create a new project

  3. Enable the Custom Search API:

    Navigate to "APIs & Services" → "Library"
Search for "Custom Search API"
Click on "Custom Search API" → "Enable"

  4. Create API credentials:

    Navigate to "APIs & Services" → "Credentials"
Click "Create Credentials" → "API key"
Copy your API key

Custom Search Engine Setup

  1. Go to Programmable Search Engine

  2. Click "Add" to create a new search engine

  3. Select "Search the entire web" and name your search engine

  4. Get your Search Engine ID (cx value) from the Control Panel

Environment Configuration

Create a .env file in the root directory:

GOOGLE_API_KEY=your_api_key_here
GOOGLE_CSE_ID=your_search_engine_id_here

Add .env to your .gitignore file to protect your credentials:

echo ".env" >> .gitignore

Building Your Server

Create the Server Implementation

Create your server implementation in src/index.ts:

import dotenv from "dotenv"
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  Tool,
} from "@modelcontextprotocol/sdk/types.js";

dotenv.config();

// Define your tools
const WEB_SEARCH_TOOL: Tool = {
  name: "google_web_search",
  description: "Performs a web search using Google's Custom Search API...",
  inputSchema: {
    // Schema details here
  },
};

const IMAGE_SEARCH_TOOL: Tool = {
  name: "google_image_search",
  description: "Searches for images using Google's Custom Search API...",
  inputSchema: {
    // Schema details here
  }
};

// Server implementation
const server = new Server(
  {
    name: "google-search",
    version: "0.1.0",
  },
  {
    capabilities: {
      tools: {},
    },
  },
);

// Check for API key and Search Engine ID
const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY!;
const GOOGLE_CSE_ID = process.env.GOOGLE_CSE_ID!;

if (!GOOGLE_API_KEY || !GOOGLE_CSE_ID) {
  console.error("Error: Missing environment variables");
  process.exit(1);
}

// Tool handlers
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [WEB_SEARCH_TOOL, IMAGE_SEARCH_TOOL],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  // Implement tool handlers
});

// Run the server
async function runServer() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Google Search MCP Server running on stdio");
}

runServer().catch((error) => {
  console.error("Fatal error running server:", error);
  process.exit(1);
});

For the complete implementation details, see the repository files.

Building the Server

After completing your implementation, build the server:

npm run build

This will compile the TypeScript code to JavaScript in the dist directory.

Connecting to MCP Clients

MCP servers can be connected to various clients. Here are setup instructions for popular ones:

Claude for Desktop

macOS/Linux

  1. Open your configuration file:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

  1. Add the server configuration:

{
  "mcpServers": {
    "google_search": {
      "command": "node",
      "args": [
        "/absolute/path/to/google-search-mcp/dist/index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

Windows

  1. Open your configuration file:

code $env:AppData\Claude\claude_desktop_config.json

  1. Add the server configuration:

{
  "mcpServers": {
    "google_search": {
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\google-search-mcp\\dist\\index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

  1. Restart Claude for Desktop

  2. Verify the tools appear by clicking the tool icon in the interface

VSCode with Claude

macOS/Linux & Windows

  1. Install the MCP Extension for VSCode

  2. Create or edit .vscode/settings.json in your workspace:

For macOS/Linux:

{
  "mcp.servers": {
    "google_search": {
      "command": "node",
      "args": [
        "/absolute/path/to/google-search-mcp/dist/index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

For Windows:

{
  "mcp.servers": {
    "google_search": {
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\google-search-mcp\\dist\\index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

  1. Restart VSCode

  2. The tools will be available to Claude in VSCode

Cursor

  1. Open Cursor settings (gear icon)

  2. Search for "MCP" and open MCP settings

  3. Click "Add new MCP server"

  4. Configure with similar settings to above:

For macOS/Linux:

{
  "mcpServers": {
    "google_search": {
      "command": "node",
      "args": [
        "/absolute/path/to/google-search-mcp/dist/index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

For Windows:

{
  "mcpServers": {
    "google_search": {
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\google-search-mcp\\dist\\index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here",
        "GOOGLE_CSE_ID": "your_search_engine_id_here"
      }
    }
  }
}

  1. Restart Cursor

Testing Your Server

Using with Claude

Once connected, you can test the tools by asking Claude questions like:

  • "Search for the latest news about renewable energy"

  • "Find images of electric vehicles"

  • "What are the top tourist destinations in Japan?"

Claude will automatically use the appropriate search tool when needed.

Manual Testing

You can also test your server directly:

# Test web search
echo '{
  "jsonrpc": "2.0",
  "method": "callTool",
  "params": {
    "name": "google_web_search",
    "arguments": {
      "query": "test query",
      "count": 2
    }
  },
  "id": 1
}' | node dist/index.js

What's Happening Under the Hood

When you ask a question:

  1. The client sends your question to Claude

  2. Claude analyzes the available tools and decides which to use

  3. The client executes the chosen tool through your MCP server

  4. The results are sent back to Claude

  5. Claude formulates a natural language response based on the search results

  6. The response is displayed to you

Troubleshooting

Common Issues

Environment Variables

If you see Error: GOOGLE_API_KEY environment variable is required:

# Check your .env file
cat .env

# Try setting environment variables directly:
export GOOGLE_API_KEY=your_key_here
export GOOGLE_CSE_ID=your_id_here

API Errors

If you encounter API errors:

# Test your API credentials directly
curl "https://www.googleapis.com/customsearch/v1?key=YOUR_API_KEY&cx=YOUR_CX_ID&q=test"

Connection Issues

If your client can't connect to the server:

# Verify the server runs correctly on its own
node dist/index.js

# Check file permissions
chmod 755 dist/index.js

# Ensure you're using absolute paths in your configuration

API Reference

google_web_search

Performs a web search using Google's Custom Search API.

Parameters:

  • query (string, required): The search query

  • count (number, optional): Number of results (1-10, default 5)

  • start (number, optional): Pagination start index (default 1)

  • site (string, optional): Limit search to specific site (e.g., 'example.com')

google_image_search

Searches for images using Google's Custom Search API.

Parameters:

  • query (string, required): The image search query

  • count (number, optional): Number of results (1-10, default 5)

  • start (number, optional): Pagination start index (default 1)

Limitations

  • Free tier of Google Custom Search API: 100 queries per day

  • Server-enforced rate limit: 5 requests per second

  • Maximum 10 results per query (Google API limitation)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Available Tools

2 tools
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: google_image_search is for finding images, while google_web_search is for general web content like articles and news. There is no overlap in functionality, making it easy for an agent to choose the correct tool based on the need for visual vs. textual information.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern with 'google_' prefix and descriptive suffixes (_image_search, _web_search). The naming is uniform and predictable, adhering to snake_case throughout without any deviations or mixed conventions.

Tool Count4/5

With only 2 tools, the server is minimal but reasonable for a search-focused domain, covering image and web searches. It might feel slightly thin if broader search capabilities (e.g., video, news-specific) were expected, but it's well-scoped for basic search needs without being overloaded.

Completeness4/5

For a Google Search server, the tools cover the core search operations: image and web searches. Minor gaps exist, such as lack of specialized search types (e.g., video, scholarly articles) or advanced filtering options, but agents can work around this with the provided tools for most common queries.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/hunter-arton/google_search_mcp_server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server