Google Search MCP Server (SERP)

Claude, Cursor, Windsurf 및 기타 모든 MCP 클라이언트에 8가지 읽기 전용 Google 검색 도구를 제공하는 호스팅형 Model Context Protocol(MCP) 서버입니다. AI Overview와 People Also Ask가 포함된 실시간 SERP를 가져오고, Google AI Mode 쿼리를 실행하며, 뉴스·쇼핑·제품 상세·짧은 동영상 결과를 모두 구조화된 JSON으로 읽을 수 있습니다. Google Cloud 프로젝트나 검색 엔진 설정은 필요 없습니다.

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

"SERP"와 "Google Search"는 여기에서 같은 제품을 의미합니다. 이 서버는 파싱된 Google 검색 엔진 결과 페이지를 반환합니다.

목차

• 필요 사항

• 빠른 시작

• 예시 프롬프트

• 도구

• 오류 및 오류 경로

• 요금, 무료 티어 및 한도

• 도구 선택

• 비교

• FAQ

• HasData 링크

• 개발

• 기여

• 라이선스

Related MCP server: Serper Search MCP Server

필요한 사항

streamable HTTP + custom header를 지원하는 MCP 클라이언트가 필요합니다. 대시보드에서 만들어 간편하게 무료로 생성할 수 있으며, 도구에 따라 약 100~200회 통화까지입니다. 그 외에는 아무것도 필요 없습니다. 원격 서버이므로 URL과 헤더만 설정하세요. Google Cloud 프로젝트나 프로그래밍 가능 검색 엔진을 구축할 필요가 없습니다. stdio 전용 클라이언트는 @hasdata/google-search-mcp(npm) 또는 hasdata-google-search-mcp(PyPI) 실행판을 사용하면 됩니다.

빠른 시작

서버 URL은 모든 클라이언트에서 동일합니다. Claude Code와 Claude Desktop에서 직접 실행해 봤습니다. 다른 블록은 원격 서버를 위한 각 클라이언트의 문서화된 형식을 따릅니다.

OAuth를 지원하는 클라이언트는 동일한 URL을 커넥터로 추가하고 구성 파일에 키를 넣지 않고 로그인할 수 있습니다.

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

Claude Desktop은 구성 파일에서 로컬(stdio) 서버만 로드하므로 원격 서버를 stdio 런처로 접속합니다. @hasdata/google-search-mcp 패키지가 바로 그런 런처이며 환경 변수에서 키를 읽습니다.

claude_desktop_config.json:

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

Python을 사용하시겠습니까? 노드 대신 PyPI 패키지로 런처를 바꾸면 uvx가 수동 설치 없이 실행합니다:

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

OAuth를 지원하는 클라이언트는 대신 URL을 사용자 지정 커넥터로 추가하고 런처를 건너뛸 수 있습니다.

.cursor/mcp.json:

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

~/.codeium/windsurf/mcp_config.json:

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

{
  "mcpServers": {
    "google-search": {
      "url": "https://mcp.hasdata.com/api/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/api/mcp?apis=google_serp",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

~/.gemini/settings.json:

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

예시 프롬프트

Google에서 best running shoes를 검색해서 유기 결과 상위 10개와 AI Overview를 알려 줘.

한 번 호출, 10크레딧입니다. SERP 응답에는 AI Overview가 유기 결과와 함께 인라인으로 포함됩니다.

같은 쿼리에서, 각 People Also Ask(사람들이 특별히 관심은) 요소 질문에 대한 AI Overview 답변을 출처와 함께 가져와 줘.

질문당 한 번 호출, 5크레딧. 각 relatedQuestions 항목은 aiOverview.pageToken을 포함하며, AI Overview 도구가 그 토큰을 답변 블록과 참조로 변환합니다.

Google AI Mode 에 what is the Model Context Protocol 을 물어보고 인용과 함께 답변을 알려 줘.

한 번 호출, 10크레딧. AI Mode는 참조 목록이 있는 생성된 답변을 텍스트 블록으로 반환합니다.

Google 쇼핑에서 검색 nike air max에 대한 전체 제품 카드를 가져와 상위 결과: 판매 매장, 가격 범위, 리뷰 분석까지 포함해서 알려 줘.

두 번 호출합니다. 쇼핑은 10크레딧이며 제품마다 토큰을 반환하고, 몰입형 제품 도구는 5크레딧으로 그 토큰을 상점·변형·리뷰로 확장합니다.

artificial intelligence에 대한 최신 Google News를 가져오고, 그리고 cooking pasta 에 대한 짧은 동영상 결과를 가져와 줘.

두 번 호출, 각각 10크레딧입니다.

워크플로우는 두 가지 체인에 의존합니다. SERP 응답은 aiOverview가 인라인으로 들어 있고 relatedQuestions 의 각 질문에 pageCode가 있는데, Google 생성형 답변을 추출하는 것은 검색과 함께 무료이거나 질문당 5크레딧 후속 호출로 해결됩니다. 쇼핑 결과도 마찬가지로 제품마다 토큰을 반환하므로 목록에서 전체 다중 매장 카드로 가는 것은 일회 호출입니다.

도구

8가지 도구, 모두 읽기 전용입니다. 아래 샘플은 실제 응답에서 자른 것이며 그 안의 결과는 Google이 변경됨에 따라 달라질 수 있으므로 형식으로 봐 주세요. 각 도구 이름은 해당 엔드포인트 정보로 연결됩니다.

샘플은 페이로드일 뿐, 전체 응답이 아닙니다. tools/call 결과는 하나의 텍스트 블록을 가지며 그 텍스트에는 url, status, text 및 json 키가 있고 스크래핑된 데이터는 json 아래에 있습니다. 원시 JSON-RPC 응답에서 경로는 result.content[0].text를 파싱한 다음 .json입니다. 채팅 클라이언트는 이 경로를 자동으로 풀어주며, 엔드포인트에 직접 통신하는 코드는 아닙니다.

Google SERP

hasdata_google_serp_serp_getSearchResults

쿼리에 대한 전체 결과 페이지입니다.

반환되는 것은 searchInformation, organicResults, aiOverview, relatedQuestions, relatedSearches, perspectives, immersiveProducts 및 pagination으로, 쿼리에 따라 Google이 보여주는 블록만 포함됩니다. 유기 검색 항목에는 position, title, link, displayedLink, source, snippet, snippetHighlitedWords, date, images가 있습니다.

AI Overview는 두 가지 방식으로 오게 되어 있습니다. 보통 aiOverview는 textBlocks 및 references와 함께 인라이닝되어 바로 읽을 수 있습니다. 가끔 Google이 이를 토큰 뒤에 숨기는데, 그 경우 aiOverview는 블록 대신 pageToken과 hasdataLink를 갖습니다. relatedQuestions의 모든 항목도 여기에 해당합니다. 위 항목은 question과 동일한 pageToken 및 hasdataLink를 포함하는 aiOverview를, 아래 AI Overview 도구가 확장합니다. 즉 People Also Ask 답변은 AI Overview로서 한 번에 하나씩 토큰을 가져와 얻게 됩니다. 최상위 aiOverview는 대체로 인라인이며 일부 쿼리에서는 토큰이므로 두 방식을 모두 감안해 읽어야 합니다.

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

AI Overview에 있는 토근을 답변으로 확장합니다.

반환 값은 aiOverview이며 textBlocks와 references를 가집니다. SERP가 블록이 아닌 토큰으로 AI Overview를 반환했을 때, 그리고 각 People Also Ask를 인용된 답변으로 변환할 때 이 도구로 읽습니다.

토큰은 약 4분간 유효합니다. 만료된 토큰은 빈 응답으로 오지 않으며 도구 오류로 실패합니다. isError: true에 HasData API error: 400 Bad Request 텍스트가 표시됩니다. 잘못된 키를 처리하는 것과 마찬가지로 처리하고, 새 토큰을 받기 위해 SERP를 다시 실행하세요.

{
  "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 AI Mode 응답, 곧 대화형 검색 결과입니다.

반환 값은 textBlocks와 references로 생성된 답변과 답변이 인용한 출처입니다.

Google SERP Light

hasdata_google_serp_serp_light_getSearchResults

페이지의 핵심을 반환하는 더 저렴한 검색입니다.

organicResults, aiOverview, relatedSearches, filters, appliedLocation, searchInformation 및 pagination을 반환합니다. 이 옵션은 전체 SERP 크레딧의 절반이며, 추가 블록 없이 유기적 결과와 AI Overview만 필요할 때 사용합니다.

Google News

hasdata_google_serp_news_getGoogleNews

쿼리 또는 뉴스 섹션에 대한 Google News 결과입니다.

newsResults, menuLinks, relatedTopics 및 relatedPublications을 반환합니다. 각 뉴스 항목에는 position, title, link, name과 icon이 포함된 source, thumbnail, date가 담겨 있습니다.

Google Shopping

hasdata_google_serp_shopping_getSearchResults

쿼리에 대한 쇼핑 결과입니다.

shoppingResults, filters, refineSearchFilters, searchInformation 및 pagination을 반환합니다. 각 결과에는 position, title, productId, price, extractedPrice, rating, reviews, source, category, thumbnail 및 immersiveProductPageToken이 포함되어 있습니다.

immersiveProductPageToken은 아래의 Immersive product 도구에 전달하는 입력값입니다. 임시 토큰이므로 제품 데이터를 원한다면 토큰이 유효한 동안 확장하고, 이전 토큰이 실패하면 쇼핑 호출을 다시 실행하여 새 토큰을 받으세요.

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

쇼핑 결과 뒤에 있는 전체 제품 카드입니다.

title, brand, rating, reviews, priceRange, 각 판매자의 가격과 링크가 담긴 stores 배열, 그리고 variants, reviews이미지, userReviews, topInsights, aboutTheProduct, discussionsAndForums를 포함하는 productResult productResults 객체를 반환합니다. 단일 목록을 스토어 전체를 아우르는 그림으로 바꿔 주는 유일한 호출입니다.

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

storesNextPageToken을 nextPageToken 매개변수로 다시 입력하면 스토어 목록을 페이지 단위로 넘겨볼수 있습니다.

Google Short Video

Google이 쿼리에 대해 보여주는 짧은 동영상 결과입니다.

shortVideos를 반환하며, 각 항목에는 position, title, link, source, sourceLogo, profileName, duration, clip 및 thumbnail이 포함됩니다.

오류 및 실패 경로

클라이언트가 도구 호출에서 HTTP 오류 코드를 보는 경우는 거의 없습니다. MCP 레이어가 200으로 응답하고 오류를 결과 내부에 넣되, isError를 true로 설정하고 사유를 텍스트로 전달합니다. 에이전트는 상태 줄을 기대할 자리에 메시지를 읽게 됩니다.

잘못된 키는 연결 실패가 아니라 도구 출력으로 나타납니다. 도구 목록은 비어 있지 않은 키면 무엇이든 허용하며, 클라이언트는 핸드셰이크를 마치고 초록불을 표시합니다. 그러면 첫 도구 호출이 isError: true와 HasData API error: 401 Unauthorized 텍스트와 함께 반환됩니다. 흐름의 앞에서는 문제를 보고해 주는 것이 없으므로 이 문자열을 주시해야 합니다.

실제 HTTP 오류는 키 없음 하나뿐입니다. 인증이 모든 도구보다 앞서 실행되며 연결 자체가 401로 실패합니다.

스키마에 어긋나는 인수는 검색이 되기 전에 거부됩니다. q가 없는 검색은 isError: true와 필드 이름을 명시한 MCP error -32602: Input validation error 텍스트로 반환됩니다. 데이터는 임의의 것도 가져오지 않으며 요금도 청구되지 않습니다.

만료된 AI Overview 토큰은 오류로 처리됩니다. SERP 응답 토큰의 유효 시간은 약 4분입니다. 이전에 저장해 둔 토큰을 확장하면 isError: true와 HasData API error: 400 Bad Request 텍스트가 반환되는데, 잘못된 키와 같은 형태입니다. 이 오류를 잡아서 SERP를 다시 실행해 새 토큰을 받아야 합니다.

Google이 표시하지 않은 블록은 빈 값이 아니라 존재하지 않는 값입니다. AI Overview나 쇼핑 패널, People Also Ask가 없는 쿼리에는 해당 키가 포함되어 있지 않습니다. 키를 읽기 전에 존재 여부를 확인하세요.

데이터를 담은 결과에는 지원 문의에 인용할 수 있는 requestMetadata.id와 해당 호출에 대한 저장된 html 및 json 링크도 포함됩니다.

요금, 무료 등급 및 한도

크레딧은 도구별로 정해져 있습니다. 전체 SERP, AI Mode, News, Shopping, 짧은 동영상은 호출당 10크레딧입니다. SERP Light, Immersive product, AI Overview 도구는 5크레딧입니다. SERP 응답에 인라인으로 포함된 AI Overview는 무료이며 전체 SERP 10크레딧에 포함되지만, AI Overview 도구로 토큰을 펼치는(모든 People Also Ask 토큰 포함) 작업은 별도로 5크레딧 호출입니다. 응답 크기에 따라 가격은 달라지지 않습니다.

무료 체험은 카드 없이 30일간 1,000크레딧이며, 전체 SERP 100회 호출 또는 5크레딧 호출 200회에 해당합니다. 그 후에는 활성 계정의 잔액이 100크레딧 아래로 떨어지면 매일 100크레딧이 보충되므로, 소량 트래픽의 에이전트는 무료 등급에서 계속 운영될 수 있습니다.

유료 요금제는 월 200,000크레딧에 $49부터 시작합니다. 크레딧당 가격은 볼륨이 커질수록 내려가며 최근 가격은 요금 페이지에서 확인하세요.

플랜은 동시 실행 수에도 제한을 둡니다. 무료 체험은 한 번에 1개 요청, Startup 15, Business 30, Growth 50, 고용량 플랜은 200~1,500입니다. 동시 실행 수만이 유일한 조절 항목이며 별도의 분당 요청 한도는 없습니다. 비인증 환경에서는 과부하를 방어적으로 처리하세요. 여러 쿼리로 퍼져나가는 에이전트는 당신보다 먼저 한계에 도달할 수 있기 때문입니다.

도구 선택

?apis=google_serp는 여덟 가지 도구를 노출합니다. 이 매개변수는 목록을 받으며, ?apis=google_serp,google_maps를 사용하면 Google Maps 도구가 검색과 함께 추가됩니다. 매개변수를 제거하면 현재 HasData가 제공하는 57가지 도구를 모두 접근할 수 있습니다.

이런 좁은 목록이 보통 더 나은 기본값입니다. 57개 중에서 선택해야 하는 모델보다 8개 중에서 선택하는 모델이 올바른 도구를 더 자주 고르며, 도구 설명 자체가 턴마다 문맥을 소비합니다.

다른 모델과의 비교

Google은 더 이상 범용 검색 API를 제공하지 않습니다. 공식 경로는 Custom Search JSON API이며, 그 API는 이 서버와 다른 질문을 다룹니다.

Custom Search JSON API은 사용자가 구성하는 Programmable 검색 엔진, 즉 직접 지정한 사이트 또는 사용자가 설정한 전체 웹 인덱스를 검색합니다. 이 API는 하루 최대 100건의 무료 쿼리 한도가 있고 이후 백분율으로 요금이 부과되며 일일 한도까지 적용되며, 축소된 결과 집합을 반환합니다. AI Overview, People Also Ask, 로컬 팩, 쇼핑, 뉴스, 짧은 동영상은 반환되지 않습니다. 이들은 현재 페이지에 나타나는 기능이지 API의 기능이 아니기 때문입니다. 자신의 사이트나 고정된 사이트 집합을 검색하면서 Google 공식 조건에 적합하게 하려면 그 API가 적합합니다.

이 서버는 방문자가 보는 실제 Google 결과 페이지를 그대로 구문 분석해 반환합니다. 설정할 것이 없으며, 검색이 특정 엔진이 아니라 Google 전체를 대상으로 실행되고, AI Overview, People Also Ask, 쇼핑 등이 구조화된 블록으로 반환됩니다.

두 가지 행이 판단을 결정합니다. 자체 사이트를 검색하는 용도고, 그에 맞는 Google 공식 API를 원한다면 Custom Search JSON API가 맞습니다. 원하는 것이 실제 SERP와 그 AI Overview 또는 Google이 검색 사용자에게yễn 보여주는 어떤 패널이라면, 공식 API는 그 기능을 제공하지 않으며 이 서버가 제공합니다.

이 서버가 하지 않는 것. 결과 페이지 뒤의 실제 페이지를 크롤링하지 않으며, 순위 이력 랭킹history를 제공하지 않고, 쓰기(write) 작업을 아무것도 하지 않습니다. parsed 결과 페이지를 반환합니다.

FAQ

Google Search MCP 서버란 무엇인가요?

Google 검색 결과를 AI 클라이언트가 호출할 수 있는 도구로 노출하는 서버입니다. 클라이언트는 Model Context Protocol을 통해 도구 호출을 보내고, 서버는 결과 페이지를 가져와 구조화된 JSON으로 반환하며, 모델은 그 결과를 가지고 작업하고 HTML 페이지는 결코 보지 않습니다. 이 서버는 읽기 전용 도구 8개를 노출하고 원격으로 실행되므로, 클라이언트는 URL에 연결만 하면 로컬 프로세스를 시작하지 않습니다.

여기서 SERP는 Google Search와 같은 의미인가요?

네. SERP는 검색 엔진 결과 페이지(Search Engine Results Page)를 뜻합니다. 이 도구들은 Google의 결과 페이지를 반환하므로, 이 저장소에서 "SERP API"와 "Google Search API"는 같은 의미입니다.

공식 Google Search MCP 서버가 있나요?

Google은 공식 MCP 서버나 일반적인 검색 API를 제공하지 않습니다. 가장 가까운 공식 제품은 사용자가 직접 구성하는 Programmable Search Engine을 검색하는 Custom Search JSON API입니다. 이 서버를 포함한 여러 커뮤니티 MCP 서버는 대신 실시간 결과 페이지를 반환합니다.

AI Overview를 어떻게 얻나요?

SERP 호출을 실행하세요. aiOverview는 보통 textBlocks와 references와 함께 인라인으로 반환됩니다. 대신 pageToken으로 반환되는 경우와 모든 People Also Ask 질문에서는 그 토큰을 AI Overview 도구에 전달하면 답변을 얻을 수 있습니다. 토큰은 빨리 만료되므로 새 호출에서 확장하세요.

Google Cloud 프로젝트나 Programmable Search Engine이 필요한가요?

아니요. 유일한 자격 증명은 사용자의 HasData 키입니다. Google Cloud에서 만들 계획가 없고, API별 쿼터를 관리할 필요도 없습니다.

API 키는 만료되나요?

아니요. 키는 만료되지 않습니다. 필요할 때 대시보드에서 언제든지 교체하세요.

데이터는 실시간인가요, 캐시된 것인가요?

실시간입니다. 각 호출은 요청 시점에 결과 페이지를 가져오며 고유한 requestMetadata.id를 지닙니다. 동일한 호출 두 개는 각각 별도의 가져오기이며 저장된 복사본을 재생하는 것이 아닙니다.

Google과 관련이 있나요?

아니요. HasData는 독립적인 서비스이며 Google과 제휴, 보증, 자금관계를 확인합니다. Google은 해당 소유자의 상표입니다. 도구는 공개적으로 이용 가능한 데이터만 다루며, Google 과 적용되는 법률에 따라 사용 베이스는 사용세요.

HasData links

이 리포지토리는 원격 서버를 위한 구성과 문서입니다. 빌드 단계가 없고, 컨테이너화할 것도 없습니다.

그 유닛은 계약 테스트(contract test)를 포함하고 있습니다. README는 특정 매개변수를 가진 8개의 도구를 문서화하며, 상위 특별한 목록 상위 목록은 커밋 없이도 잘 변경될 수 있습니다. 그래서 이 문서가 조용히 잘못된 정보를 전할 수 있습니다. 테스트는 문서화된 도구가 주장한 매개변수 형태로 존재하는지를 확인하고, CI에서 매주, 그리고 모든 push에서 실행합니다.

HASDATA_API_KEY=your_key_here npm test

PowerShell에서:

$env:HASDATA_API_KEY = "your_key_here"; npm test

마지막 확인은 실주고 10크레딧이 소모되는데, 이는 올바른 이유로 실패할 수 있는 카나리(canary)을 얻는 대가입니다. 키 목록 조회는 어떤 비어 있지 않은 키로도 성공하므로, 도구 목록만 하는 테스트는 만료된 키로도 계속 초록색을 유지합니다.

기여

도구 팁과 응답 성공 밒이 정말 유용한 기여입니다. 이 부분들이 원본과 가장 많이 어긋나기 때문입니다. 실행한 호출과 받은 응답가을 꼭 포함해 주세요. 포크된 클라이언트의 Pull Request는 키 없이 테스트를 실행하고, 실시간검사는 빨간색 띄는 대신 건너뛰스니다.

라이선스

MIT. LICENSE를 참조하세요.