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.

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.