google-search-mcp

# Google Search MCP Server (SERP)

A hosted Model Context Protocol (MCP) server that gives Claude, Cursor, Windsurf and any other MCP client eight read-only Google Search tools. Pull the live SERP with its AI Overview and People Also Ask, run a Google AI Mode query, and read news, shopping, product detail and short-video results, all as structured JSON, with no Google Cloud project and no search-engine setup.

```
https://mcp.hasdata.com/api/mcp?apis=google_serp
```

[![tool contract](https://github.com/HasData/google-search-mcp/actions/workflows/contract.yml/badge.svg)](https://github.com/HasData/google-search-mcp/actions/workflows/contract.yml)
[![MCP](https://img.shields.io/badge/MCP-remote%20%7C%20streamable%20HTTP-6366f1?style=flat-square)](https://modelcontextprotocol.io)
[![Tools](https://img.shields.io/badge/tools-8-10b981?style=flat-square)](#tools)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

"SERP" and "Google Search" are the same product here. This server returns Google search-engine results pages, parsed.

## Contents

- [What you need](#what-you-need)
- [Quick start](#quick-start)
- [Example prompts](#example-prompts)
- [Tools](#tools)
- [Errors and failure paths](#errors-and-failure-paths)
- [Pricing, free tier and limits](#pricing-free-tier-and-limits)
- [Tool selection](#tool-selection)
- [How it compares](#how-it-compares)
- [FAQ](#faq)
- [HasData links](#hasdata-links)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## What you need

An MCP client that speaks streamable HTTP with custom headers. A HasData API key from the [dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=google-search-mcp), free to create with no card, and the trial covers about 100 to 200 calls depending on the tool. Nothing else. This is a remote server, nothing to install. And there is no Google Cloud project or Programmable Search Engine to set up.

## Quick start

| | |
| :--- | :--- |
| URL | `https://mcp.hasdata.com/api/mcp?apis=google_serp` |
| Transport | HTTP, streamable |
| Auth header | `x-api-key: HASDATA_API_KEY` |

The server URL is the same for every client. We run it hands-on in Claude Code and Claude Desktop. The other blocks follow each client's own documented format for a remote server.

Clients with OAuth support can add the same URL as a connector and sign in without putting a key in a config file.

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --transport http google-search "https://mcp.hasdata.com/api/mcp?apis=google_serp" \
  --header "x-api-key: HASDATA_API_KEY"
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Claude Desktop loads only local (stdio) servers from its config file, so a remote server is reached through the `mcp-remote` bridge. Node has to be on the machine.

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "google-search": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.hasdata.com/api/mcp?apis=google_serp",
        "--header",
        "x-api-key:HASDATA_API_KEY"
      ]
    }
  }
}
```

The `x-api-key:` value carries no space after the colon. Claude Desktop passes the argument without a shell, and a space splits the header. A client with OAuth support can instead add the URL as a custom connector and skip the bridge.

</details>

<details>
<summary><b>Cursor</b></summary>

`.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "google-search": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_serp",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

`~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "google-search": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=google_serp",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Cline</b></summary>

```json
{
  "mcpServers": {
    "google-search": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_serp",
      "type": "streamableHttp",
      "headers": { "x-api-key": "HASDATA_API_KEY" },
      "disabled": false
    }
  }
}
```

</details>

<details>
<summary><b>VS Code</b></summary>

`.vscode/mcp.json`:

```json
{
  "servers": {
    "google-search": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_serp",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Gemini CLI</b></summary>

`~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "google-search": {
      "httpUrl": "https://mcp.hasdata.com/api/mcp?apis=google_serp",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

## Example prompts

> Search Google for `best running shoes` and give me the organic top ten plus the AI Overview.

*One call, 10 credits. The SERP response carries the AI Overview inline alongside the organic results.*

> For the same query, take each People Also Ask question and pull its AI Overview answer with sources.

*One call per question, 5 credits each. Each `relatedQuestions` entry holds an `aiOverview.pageToken`, and the AI Overview tool turns that token into the answer blocks and their references.*

> Ask Google AI Mode `what is the Model Context Protocol` and give me the answer with its citations.

*One call, 10 credits. AI Mode returns the generated answer as text blocks with a reference list.*

> Search Google Shopping for `nike air max`, then pull the full product card for the top result: every store selling it, the price range and the review breakdown.

*Two calls. Shopping is 10 credits and returns a token per product, and the immersive product tool spends 5 to expand that token into stores, variants and reviews.*

> Get the latest Google News for `artificial intelligence`, and separately the short-video results for `cooking pasta`.

*Two calls, 10 credits each.*

The workflow leans on two chains. A SERP response hands back an `aiOverview` inline and a `pageToken` on every People Also Ask question, so extracting Google's generative answers is either free with the search or one 5-credit follow-up per question. A shopping result likewise hands back a token per product, so the jump from a listing to its full multi-store card is a single call.

## Tools

Eight tools, all read-only. Samples below are trimmed from real calls, and the results in them change as Google changes, so read them as shapes. Each tool name links to its endpoint reference.

The samples are the payload, not the whole response. A `tools/call` result carries one text block, and that text is itself JSON holding `url`, `status`, `text` and `json`, with the scraped data under `json`. From a raw JSON-RPC response the path is `result.content[0].text`, parsed, then `.json`. A chat client unwraps that for you and code talking to the endpoint directly does not.

### Google SERP

[`hasdata_google_serp_serp_getSearchResults`](https://docs.hasdata.com/apis/google-serp/serp?utm_source=github&utm_medium=syndication&utm_campaign=google-search-mcp)

The full results page for a query.

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `q` | string | yes | The search query, exactly as a user would type it |
| `gl` / `hl` | string | | Two-letter country and language codes |
| `location` / `uule` | string | | Geographic location for the search, by name or as a `uule` string |
| `num` | number | | Approximate results per page. Google now caps a page at about ten and ignores anything higher, so `num` above 10 fetches no more |
| `start` | number | | Result offset for paging |
| `tbm` / `tbs` | string | | Search type and advanced filters, the raw Google parameters |
| `deviceType` | string | | `desktop`, `mobile` or `tablet` |

Returns `searchInformation`, `organicResults`, `aiOverview`, `relatedQuestions`, `relatedSearches`, `perspectives`, `immersiveProducts` and `pagination`, with whichever blocks Google shows for the query. Organic entries carry `position`, `title`, `link`, `displayedLink`, `source`, `snippet`, `snippetHighlitedWords`, `date` and `images`.

> The AI Overview arrives two ways. Usually `aiOverview` is inline, with `textBlocks` and `references` you can read straight away. Sometimes Google gates it behind a token, and then `aiOverview` carries a `pageToken` and a `hasdataLink` instead of the blocks. Every `relatedQuestions` entry is that second case too. It holds a `question` and an `aiOverview` with the same `pageToken` and `hasdataLink`, which the AI Overview tool below expands. So the People Also Ask answers are AI Overviews you fetch one token at a time. The top-level `aiOverview` is inline on most queries and a token on a few, so read it both ways.

```json
{
  "organicResults": [
    {
      "position": 1,
      "title": "The 15 Best Running Shoes of 2026",
      "link": "https://www.runnersworld.com/gear/a19663621/best-running-shoes/",
      "source": "Runner's World",
      "snippet": "The Brooks Ghost is our No. 1 shoe when we recommend new trainers…"
    }
  ],
  "aiOverview": {
    "textBlocks": [ { "type": "paragraph", "snippet": "The best running shoes depend on your goal…" } ],
    "references": [ { "index": 0, "title": "7 Best Running Shoes in 2026 - RunRepeat", "link": "https://runrepeat.com/guides/best-running-shoes" } ]
  },
  "relatedQuestions": [
    { "question": "What are the top 5 best running shoes?", "aiOverview": { "pageToken": "eyJpZCI6…", "hasdataLink": "https://api.hasdata.com/scrape/google/ai-overview?pageToken=eyJpZCI6…" } }
  ],
  "pagination": { "next": "…" }
}
```

### Google AI Overview

[`hasdata_google_serp_ai_overview_getAiOverviewResponse`](https://docs.hasdata.com/apis/google-serp/ai-overview?utm_source=github&utm_medium=syndication&utm_campaign=google-search-mcp)

Expands an AI Overview token into its answ