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.

1,000 free credits every month, no card required, which is 100 full-SERP calls or 200 of the 5-credit calls.

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

• Prompts and resources

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

Contents

• What you need
• Quick start
• Example prompts
• Tools
• Errors and failure paths
• Pricing, free tier and limits
• Tool selection
• How it compares
• FAQ
• HasData links
• Development
• Contributing
• License

What you need

An MCP client that speaks streamable HTTP with custom headers. A HasData API key from the dashboard, free to create with no card, and the free tier covers about 100 to 200 calls a month depending on the tool. Nothing else. This is a remote server, so the simplest path is a URL and a header, with no Google Cloud project or Programmable Search Engine to set up. A stdio-only client can use the @hasdata/google-search-mcp (npm) or hasdata-google-search-mcp (PyPI) launcher instead.

Quick start

URL	https://mcp.hasdata.com/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.

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

Claude Desktop loads only local (stdio) servers from its config file, so it reaches a remote server through a stdio launcher. The @hasdata/google-search-mcp package is that launcher, and it reads the key from the environment.

claude_desktop_config.json:

{
  "mcpServers": {
    "google-search": {
      "command": "npx",
      "args": ["-y", "@hasdata/google-search-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

Python instead of Node? Swap the launcher for the PyPI package, which uvx runs without a manual install:

{
  "mcpServers": {
    "google-search": {
      "command": "uvx",
      "args": ["hasdata-google-search-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

A client with OAuth support can instead add the URL as a custom connector and skip the launcher.

.cursor/mcp.json:

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

~/.codeium/windsurf/mcp_config.json:

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

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

.vscode/mcp.json:

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

~/.gemini/settings.json:

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

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, 10 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

Tool	What it returns
hasdata_google_serp_ai_mode_getAiModeResponse	The conversational response text, cited source links, subtopic breakdowns, follow-up suggestions, and a subsequentRequestToken for multi-turn continuation. 10 credits a call
hasdata_google_serp_ai_overview_getAiOverviewResponse	The AI-generated answer text, referenced source URLs, and expanded subtopic sections. 10 credits a call
hasdata_google_serp_events_getEventInformation	Event title, start date/time, venue name and address, ticket/source links, description, and thumbnail. 10 credits a call
hasdata_google_serp_immersive_product_getImmersive_e29f691177	Multi-store offers (merchant, price, shipping, condition, URL), product specs, images, ratings, and the nextPageToken. 10 credits a call
hasdata_google_serp_news_getGoogleNews	Article title, snippet, source publisher, published date, thumbnail, and URL, plus tokens for navigating topics, sub-sections, and story clusters. 10 credits a call
hasdata_google_serp_product_getProductInformation	Product title, images, price, ratings, specs, merchant offers (seller, shipping, condition, total price), and review text depending on searchType. 10 credits a call
hasdata_google_serp_serp_getSearchResults	Organic results (title, link, snippet, position), ads, knowledge graph, related searches, People Also Ask, local pack, featured snippets, AI Overview pageToken, and rich…. 10 credits a call
hasdata_google_serp_serp_light_getSearchResults	Organic results (title, link, displayed link, snippet, sitelinks, extensions, date, rating and review count), AI Overview with its text blocks and source references,…. 5 credits a call
hasdata_google_serp_shopping_getSearchResults	Product title, price, merchant/source, rating, reviews count, thumbnail, product link, productId, immersiveProductPageToken, and filter chips with hasdata_link for…. 10 credits a call
hasdata_google_serp_short_videos_getShortVideosSearchResults	Video title, thumbnail, duration, source platform, channel/creator, publish date, and direct video URL. 10 credits a call

Ten 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

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.

{
  "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

Expands an AI Overview token into its answer.

Parameter	Type	Required	Notes
pageToken	string	yes	An aiOverview.pageToken from a SERP response, including the ones on relatedQuestions. The same token object carries a hasdataLink, a ready REST URL that fetches the same answer without this tool

Returns aiOverview with textBlocks and references. This is how you read the AI Overview when the SERP handed you a token rather than the blocks, and how you turn each People Also Ask question into a cited answer.

Tokens are valid for about 4 minutes. A stale one does not come back empty, it fails as a tool error, isError: true with the text HasData API error: 400 Bad Request. Catch it the way you catch a wrong key, and re-run the SERP for a fresh token.

{
  "aiOverview": {
    "textBlocks": [ { "type": "paragraph", "snippet": "The top five running shoes feature versatile options for daily training and racing…" } ],
    "references": [ { "index": 0, "title": "…", "link": "https://…" } ]
  }
}

Google AI Mode

hasdata_google_serp_ai_mode_getAiModeResponse

Google's AI Mode answer for a query, the conversational search result.

Parameter	Type	Required	Notes
q	string	yes	The question to ask AI Mode
gl / hl	string		Country and language codes
location / uule	string		Geographic location
continuable	boolean		Set true to make the answer continuable in a follow-up call
subsequentRequestToken	string		Token from a previous AI Mode response, to continue the thread

Returns textBlocks and references, the generated answer and the sources it cites.

Google SERP Light

hasdata_google_serp_serp_light_getSearchResults

A cheaper search that returns the core of the page.

Parameter	Type	Required	Notes
q	string	yes	The search query
gl / hl	string		Country and language codes
location / uule	string		Geographic location
num / start	number		Page size and offset

Returns organicResults, aiOverview, relatedSearches, filters, appliedLocation, searchInformation and pagination. It is half the credits of the full SERP, for when you want organic results and the AI Overview without the extra blocks.

Google News

hasdata_google_serp_news_getGoogleNews

The Google News results for a query or a news section.

Parameter	Type	Required	Notes
q	string		A query. Omit it to read a section instead
gl / hl	string		Country and language codes
topicToken / sectionToken / storyToken / publicationToken	string		Drill into a topic, section, story or publication, using a token from a previous response

Returns newsResults, menuLinks, relatedTopics and relatedPublications. Each news entry carries position, title, link, source with a name and icon, thumbnail and date.

Google Shopping

hasdata_google_serp_shopping_getSearchResults

Shopping results for a query.

Parameter	Type	Required	Notes
q	string	yes	The product query
gl / hl	string		Country and language codes
location / uule	string		Geographic location
start	number		Result offset for paging
tbs	string		Advanced shopping filters, the raw Google parameter

Returns shoppingResults, filters, refineSearchFilters, searchInformation and pagination. Each result carries position, title, productId, price, extractedPrice, rating, reviews, source, category, thumbnail and an immersiveProductPageToken.

immersiveProductPageToken is the input to the immersive product tool below. It is a temporary token, so expand it while it is fresh if you want the product data, and re-run the shopping call for a new one if an old token fails.

{
  "shoppingResults": [
    {
      "position": 1,
      "title": "Men's Nike Alphafly 3",
      "productId": "13366226642799457284",
      "price": "$285.00",
      "extractedPrice": 285,
      "rating": 4.5,
      "reviews": 120,
      "source": "Nike",
      "immersiveProductPageToken": "eyJyZHMiOiJQQ18…"
    }
  ]
}

Immersive product

hasdata_google_serp_immersive_product_getImmersive_e29f691177

The full product card behind a shopping result.

Parameter	Type	Required	Notes
pageToken	string	yes	The immersiveProductPageToken from a shopping result or a SERP immersiveProducts entry
moreStores	boolean		Ask for more stores
nextPageToken	string		Page through the list of stores, using storesNextPageToken from the previous response

Returns a productResults object with title, brand, rating, reviews, priceRange, a stores array of every seller with its price and link, plus variants, reviewsImages, userReviews, topInsights, aboutTheProduct and discussionsAndForums. This is the one call that turns a single listing into the whole cross-store picture.

{
  "productResults": {
    "title": "Men's Nike Alphafly 3",
    "brand": "Nike",
    "rating": 4.4,
    "reviews": 1077,
    "priceRange": "$221-$295",
    "stores": [ { "name": "eBay", "link": "https://www.ebay.com/itm/…", "price": "$221" } ],
    "storesNextPageToken": "Mw=="
  }
}

Feed storesNextPageToken back in as the nextPageToken parameter to page through the stores.

Google short videos

hasdata_google_serp_short_videos_getShortVideosSearchResults

The short-video results Google shows for a query.

Parameter	Type	Required	Notes
q	string	yes	The query
gl / hl / cr	string		Country, language and content-region codes
lr	array		One or more language restrictions
page	number		Result page
deviceType	string		desktop, mobile or tablet

Returns shortVideos, each with position, title, link, source, sourceLogo, profileName, duration, clip and thumbnail.

Prompts and resources

The server ships 5 prompts, ready-made workflows a client can offer instead of making the user compose a tool call.

Prompt	What it does
google_search	Search Google and summarize the top organic results.
google_news	Find recent news coverage on a topic.
google_shopping	Compare product offers from Google Shopping.
google_short_videos	Find short videos about a topic.
google_ai_mode	Get Google AI Mode's answer with its sources.

Alongside them the server exposes 10 resources, one per parameter whose accepted values are a fixed list. Reading one is cheaper than learning the vocabulary from a rejected call, and it costs no credits. Each URI is hasdata://google_serp/<parameter>.

Parameter	Values	What it selects
gl	245	The two-letter country code for the country you want to limit the search to.
hl	159	The two-letter language code for the language you want to use for the search.
so	2	Sort order for articles in a story. Use only with storyToken.
domain	195	Google domain to use. Default is google.com.
searchType	3	Parameter for fetching specific product information, such as 'offers', 'specs', or 'reviews'.
lr	43	The 'lr' parameter specifies the language of the websites to return results from. This parameter filters results based on the language of the web content.
safe	2	Adult Content Filtering option.
tbm	5	Specify the type of search.
deviceType	3	Specify the device type for the search.
cr	237	The country code for the country you want to limit the search to.

Both lists are served without an API key, so a client can read them before a user has signed up.

Errors and failure paths

Your client almost never sees an HTTP error code from a tool call. The MCP layer answers 200 and puts the failure inside the result, with isError set to true and the reason as text. The agent reads a message where you might expect a status line.

A wrong key surfaces as tool output, not as a failed connection. Listing tools accepts any non-empty key, and the client completes its handshake and shows green. The first tool call then comes back with isError: true and the text HasData API error: 401 Unauthorized. Watch for that string, because nothing earlier in the flow reports the problem.

The one real HTTP error is a missing key. Authorization runs before any tool, and the connection itself fails with 401.

An argument that breaks the schema is rejected before it becomes a search. A search with no q comes back with isError: true and the text MCP error -32602: Input validation error, naming the field. Nothing is fetched and nothing is charged.

A stale AI Overview token fails as an error. A SERP response token is valid for about 4 minutes. Expanding one you stored earlier comes back with isError: true and the text HasData API error: 400 Bad Request, the same shape as a wrong key. Catch it and re-run the SERP to get a fresh token.

A block Google did not show is absent, not empty. A query with no AI Overview, no shopping pane or no People Also Ask returns a response without those keys rather than with empty ones. Test for the key before reading it.

Results that carry data also carry a requestMetadata.id worth quoting in support, plus html and json links to the stored artifact of that exact call.

Pricing, free tier and limits

Credits are per tool. The full SERP, AI Mode, News, Shopping and short videos cost 10 credits a call. SERP Light, immersive product and the AI Overview tool are 5. The AI Overview that comes inline with a SERP response is free, part of that 10-credit call, but expanding a token with the AI Overview tool, including every People Also Ask token, is a separate 5-credit call. Response size does not change the price.