Google Trends MCP Server

호스팅되는 Model Context Protocol (MCP) 서버로, Claude, Cursor, Windsurf 및 다른 모든 MCP 클라이언트에 Google Trends 도구 하나를 제공합니다. 시간에 따른 관심도, 지역별 관심도, 모든 용어에 대한 상승 중 및 상위 관련 검색어와 주제를 구조화된 JSON으로 가져옵니다. 유지 관리할 스크래핑 라이브러리도, Google 계정도 필요 없습니다.

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

목차

• 필요한 것

• 빠른 시작

• 예시 프롬프트

• 도구

• 오류 및 실패 경로

• 가격, 무료 티어 및 한도

• 도구 선택

• 비교

• FAQ

• HasData 링크

• 개발

• 기여

• 라이선스

Related MCP server: HasData MCP Server

필요한 것

MCP 클라이언트와 대시보드에서 받은 HasData API 키가 필요합니다. 키는 카드 없이 무료로 만들 수 있으며, 체험판은 5크레딧 요율로 약 200회의 호출을 포함합니다. 이 서버는 원격 서버이므로 가장 간단한 방법은 URL과 x-api-key 헤더를 사용하는 것이며, 실행할 컨테이너가 필요 없고 전체 흐름에서 Google 계정도 필요 없습니다. stdio만 지원하는 클라이언트는 아래에 표시된 얇은 런처를 통해 이 서버에 접속합니다. 런처는 npm의 @hasdata/google-trends-mcp와 PyPI의 hasdata-google-trends-mcp로 게시되어 있습니다.

빠른 시작

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

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

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

설정, 커넥터, 사용자 지정 커넥터 추가 순서로 이동한 다음 https://mcp.hasdata.com/api/mcp?apis=google_trends를 붙여넣고 로그인합니다.

구성 파일 방식의 경우 Claude Desktop은 로컬(stdio) 서버만 로드하므로 stdio 런처를 통해 원격 서버에 접속합니다. @hasdata/google-trends-mcp 패키지가 바로 그 런처이며, 환경 변수에서 키를 읽습니다. claude_desktop_config.json에 다음을 추가하세요:

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

Node 대신 Python을 사용한다면 런처를 PyPI 패키지로 바꾸세요. uvx가 수동 설치 없이 실행합니다:

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

모든 프로젝트에 적용하려면 ~/.cursor/mcp.json을, 단일 프로젝트에는 .cursor/mcp.json을 사용하세요:

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

~/.codeium/windsurf/mcp_config.json에 추가하세요. Windsurf는 필드 이름을 url이 아닌 serverUrl로 사용합니다:

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

작업 공간의 .vscode/mcp.json에 추가하세요:

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

예시 프롬프트

코드가 아니라 프롬프트입니다. 하나를 붙여넣으면 에이전트가 도구를 스스로 선택합니다. 각 프롬프트는 필요한 호출 수와 함께 표시되어 있습니다. 성공적인 호출마다 5크레딧이 소모되기 때문입니다.

지난 12개월 동안 미국에서 "cold brew coffee"에 대한 관심도를 차트로 보여주고, 어느 주에 정점이었는지 알려줘.

호출 1회, 5크레딧. 주간 시계열이 단일 요청으로 반환됩니다.

미국에서 "cold brew coffee"의 상승 중인 관련 검색어를 보여주고, Breakout으로 표시된 항목을 표시해 줘.

호출 1회, 5크레딧.

전 세계적으로 5년 동안 "cold brew"와 "iced coffee"에 대한 관심도를 비교하고, 어느 쪽이 성장하고 있는지 말해 줘.

호출 1회, 5크레딧. 도구는 하나의 timeseries 요청에 여러 용어를 받습니다.

지난 90일 동안 미국 주별 "sunscreen"에 대한 관심도를 보여줘서 수요가 가장 높은 곳을 알 수 있게 해 줘.

호출 1회, 5크레딧. 주 단위 세분화의 지역별 관심도 보기입니다.

여러 용어 간 비교는 하나의 timeseries 호출로 처리됩니다. 지역별 분석, 관련 검색어, 관련 주제는 각각 별도의 dataType이므로, 차트와 상승 검색어를 모두 원하는 프롬프트는 호출이 두 번입니다.

도구

읽기 전용 도구 하나입니다. 아래 샘플은 실제 호출에서 일부를 발췌한 것이며 숫자는 트렌드에 따라 움직입니다. 형태로 보세요. 도구 이름은 전체 매개변수 목록이 있는 엔드포인트 참조 문서에 연결됩니다.

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

Google Trends 데이터 가져오기

hasdata_google_trends_search_getTrendsData

시간에 따른 관심도, 지역별 관심도, 또는 한 용어의 관련 검색어와 주제를 제공합니다.

응답 키는 dataType에 따라 달라집니다. timeseries는 interestOverTime.timelineData를 반환하고, geoMap은 지역별 관심도를 반환하며, related 유형은 relatedQueries 또는 relatedTopics를 반환하고 각각 rising과 top으로 나뉩니다. 요청한 유형과 일치하는 키를 읽으세요.

timeseries(기본값)는 각 지점에 대해 0에서 100 사이의 값을 문자열과 extractedValue의 미리 파싱된 숫자로 반환합니다. 가장 최근 지점에는 종종 isPartial: true가 표시되는데, 이는 해당 주가 아직 채워지는 중이라는 뜻입니다. 추세를 계산하기 전에 이 지점을 제거하세요. 그렇지 않으면 마지막 막대가 실제가 아닌 하락으로 읽힙니다.

{
  "interestOverTime": {
    "timelineData": [
      { "date": "Apr 12 – 18, 2026", "timestamp": "1775952000", "isPartial": false,
        "values": [{ "query": "cold brew coffee", "value": "100", "extractedValue": 100, "hasData": true }] },
      { "date": "Aug 23 – 29, 2026", "timestamp": "1787443200", "isPartial": true,
        "values": [{ "query": "cold brew coffee", "value": "44", "extractedValue": 44, "hasData": true }] }
    ]
  }
}

relatedQueries는 rising과 top으로 나뉩니다. 상승 항목은 +300% 같은 백분율로 표시되거나, 점수로 매기기에는 너무 큰 급증은 Breakout으로 표시되며, extractedValue는 그 뒤의 숫자를 제공합니다. Breakout은 실재 백분율보다 훨씬 높은 센티널 extractedValue와 함께 반환되므로 원시 숫자가 아닌 문자열 레이블로 정렬하세요.

{
  "relatedQueries": {
    "rising": [
      { "query": "organic cold brew coffee", "value": "+300%", "extractedValue": 300, "link": "https://trends.google.com/trends/explore?q=organic+cold+brew+coffee&date=today+12-m&geo=US" }
    ],
    "top": [
      { "query": "how to cold brew coffee", "value": "100", "extractedValue": 100, "link": "https://trends.google.com/trends/explore?q=how+to+cold+brew+coffee&date=today+12-m&geo=US" }
    ]
  }
}

엔드포인트 참조에는 도구가 허용하는 모든 geo, cat 및 날짜 형식이 나열되어 있습니다.

오류 및 실패 경로

클라이언트가 도구 호출에서 HTTP 오류 코드를 보는 경우는 거의 없습니다. MCP 계층은 200으로 응답하고 실패를 결과 안에 넣습니다. isError가 true로 설정되고 사유는 텍스트로 제공됩니다. 에이전트는 상태 줄이 있을 법한 자리에서 메시지를 읽습니다.

잘못된 키는 연결 실패가 아니라 도구 출력으로 드러납니다. tools/list는 비어 있지 않은 키를 모두 받아들이고 도구를 반환하므로 클라이언트는 핸드셰이크를 완료하고 정상으로 표시합니다. 그러면 첫 번째 도구 호출이 isError: true와 텍스트 HasData API error: 401 Unauthorized로 돌아옵니다. 그 문자열을 주의하세요. 흐름의 앞부분에서는 문제를 알려주는 것이 없기 때문입니다.

키 누락은 유일한 실제 HTTP 오류입니다. 인증은 모든 도구보다 먼저 실행되며 연결 자체가 401로 실패합니다. CORS 헤더가 포함되므로 브라우저 클라이언트는 불투명한 네트워크 실패가 아닌 상태 코드를 읽습니다.

도구 스키마를 위반하는 인수는 스크래핑이 되기 전에 거부됩니다. 서버는 isError: true와 텍스트 MCP error -32602: Input validation error로 응답하며 문제가 되는 필드를 명시합니다. 아무것도 가져오지 않으며 요금도 부과되지 않습니다.

검색량이 너무 적은 용어는 오류가 아니라 데이터 배열이 빈 성공 결과를 반환합니다. 희귀한 용어는 Google Trends에 표시할 내용이 없으며 requestMetadata.status는 여전히 ok로 표시됩니다. 차트를 그리기 전에 포인트가 있는지 확인하세요.

플랫폼이 거부하는 식별자는 400을 반환하며 requestMetadata.status가 error로 설정됩니다. 알 수 없는 geo 또는 cat 값이 일반적인 원인입니다.

데이터가 포함된 결과에는 지원 요청에서 인용할 만한 requestMetadata.id도 함께 제공됩니다.

가격, 무료 티어 및 한도

모든 Google Trends 호출은 성공적인 호출당 5크레딧입니다. 응답 크기는 가격을 바꾸지 않습니다. 5년치 주간 시리즈는 한 주와 같은 비용입니다.

무료 체험판은 카드 없이 30일 동안 1,000크레딧으로, Google Trends 호출 200회에 해당합니다. 이후 활성 계정은 잔액이 100 미만으로 떨어질 때마다 매일 100크레딧이 충전되므로, 사용량이 적은 에이전트는 무료 티어에서 무기한 실행될 수 있습니다.

유료 플랜은 200,000크레딧(40,000회 호출)에 월 $49부터 시작합니다. 단가는 볼륨에 따라 낮아져서 엔트리 플랜의 1,000회 호출당 $1.23부터 Business $0.50, Growth $0.42, 가장 큰 대용량 플랜에서는 $0.37입니다.

도구 선택

플랜은 또한 동시 요청 수도 결정합니다. 무료 체험판은 한 번에 1건의 요청을 허용하고, Startup은 15건, Business는 30건, Growth는 50건이며, 대용량 플랜은 200건에서 1,500건까지입니다. 무인으로 실행되는 모든 작업에서는 동시 요청 초과(overflow) 상황을 방어적으로 처리하세요.

200이 아닌 상태로 반환된 요청은 과금되지 않습니다. 결과를 찾지 못한 성공적인 호출도 여전히 호출로 간주됩니다.

도구 선택

apis 쿼리 매개변수는 에이전트가 볼 수 있는 도구를 결정합니다. 도구가 적을수록 도구 정의에 소비되는 컨텍스트가 줄어들고, 모델이 잘못된 도구를 선택할 가능성도 줄어듭니다.

?apis=google_trends              the one tool in this repo
?apis=google_trends,google_serp  add Google search
?apis=google_trends,youtube      trends plus YouTube

이 매개변수는 google_trends 같은 제공업체 이름과 개별 API 이름을 받습니다. 철자가 틀린 이름은 무시됩니다. 모든 이름이 틀렸다면 요청은 400 오류로 실패하며, 응답 본문에는 인식하지 못한 이름과 유효한 모든 값이 함께 나열됩니다. 이 매개변수를 생략하면 동일한 엔드포인트가 57개의 HasData 도구를 모두 노출합니다.

비교

Google은 공개 Trends API를 제공하지 않습니다. 일반적으로 쓰이는 두 가지 방법은 비공식 pytrends 라이브러리와 직접 스크래퍼를 만드는 방법입니다. pytrends는 Google의 내부 엔드포인트를 리버스 엔지니어링하며, Google이 엔드포인트를 변경하거나 호출자에 속도 제한을 적용하면 작동이 중단됩니다. 이 서버는 안정적인 스키마 뒤에서 그 작업을 대신 처리합니다.

이미 pytrends를 낮은 볼륨으로 실행 중이고 고장났을 때 고치는 것을 감수할 수 있다면, 그것이 여전히 무료 해법입니다. 이 서버는 매번 동일한 형태로 데이터가 도착해야 하는 에이전트와 파이프라인을 위한 것입니다.

FAQ

공식 Google Trends API가 있나요?

아니요. Google은 공개 Trends API를 출시한 적이 없습니다. 모든 옵션은 trends.google.com 사이트가 사용하는 동일한 내부 엔드포인트를 읽습니다. 이 서버는 HasData가 유지관리하며 결과를 구조화된 JSON으로 반환합니다.

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

Google Trends를 AI 클라이언트가 호출할 수 있는 도구로 노출하는 서버입니다. 클라이언트는 Model Context Protocol을 통해 도구 호출을 보내고, 서버는 데이터를 가져와 구조화된 JSON을 반환하며, 모델은 그 결과를 가지고 작업합니다. 이 서버는 단일 도구를 노출하고 원격으로 실행되므로, 클라이언트는 URL에 연결만 하면 되고 로컬 프로세스를 시작할 필요가 없습니다.

숫자는 절대 검색량을 의미하나요?

아니요. Google Trends 자체도 마찬가지입니다. 값은 요청한 쿼리, 기간, 지역 내에서 0에서 100 사이로 조정된 상대적 관심도를 나타냅니다. 검색 횟수가 아니라 추세의 형태와 비교 용도로 사용하세요.

마지막 데이터 포인트가 나머지보다 낮은 이유는 무엇인가요?

가장 최근 버킷은 보통 아직 채워지는 중이며 isPartial: true로 반환됩니다. 추세를 계산하기 전에 이를 제외하세요.

여러 용어를 한 번에 비교할 수 있나요?

네. timeseries와 geoMap에서 가능합니다. 용어를 q에 쉼표로 구분하여 전달하세요. related-query(관련 검색어) 및 related-topic(관련 주제) 유형은 단일 용어만 받습니다.

이 서버를 다른 HasData API와 함께 사용할 수 있나요?

네. apis 매개변수는 목록을 받으며, ?apis=google_trends,google_serp는 에이전트에 Trends와 Google 검색을 함께 제공합니다. 매개변수를 생략하면 모든 도구를 사용할 수 있습니다.

규정 준수 및 개인 데이터

HasData는 공개적으로 이용 가능한 데이터에만 접근합니다. 플랫폼의 이용약관이 자동 접근을 제한할 수 있으며, 규정 준수에 대한 책임은 사용자 본인에게 있습니다.

HasData 링크

개발

이 저장소는 원격 서버의 구성과 문서입니다. 빌드 단계도, 컨테이너화할 대상도 없습니다.

test/의 테스트는 도구 계약, 즉 이 저장소의 커밋 없이도 깨질 수 있는 부분을 검증합니다. 테스트는 ?apis=google_trends가 정확히 하나의 도구를 반환하는지, 여전히 필수 매개변수를 선언하는지, 이름이 변경되지 않았는지, 사용 중인 키가 실제로 승인되는지 확인합니다. 마지막 검사는 도구를 실제로 호출하며 5크레딧이 소요되는데, 이는 올바른 이유로 실패할 수 있는 카나리 테스트의 비용입니다.

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

# Windows PowerShell
$env:HASDATA_API_KEY="your_key_here"; npm test

동일한 테스트 스위트는 모든 푸시와 주 1회 예약된 일정으로 CI에서 실행됩니다. 업스트림 도구 목록은 누구도 이 저장소를 건드리지 않아도 바뀔 수 있기 때문입니다. 실패는 도구 목록이 변경되었거나, 키가 더 이상 작동하지 않거나, 엔드포인트에 연결할 수 없음을 의미하며, 단언 메시지가 그 원인을 알려줍니다.

기여

매개변수 표와 응답 샘플에 대한 수정이 가장 유용한 기여입니다. 이 부분들이 실제로 변동이 잦은 부분이기 때문입니다. 수행한 호출과 받은 응답을 함께 포함해 주세요. 포크에서 온 풀 리퀘스트는 키 없이 테스트 스위트를 실행하며, 실시간 검사는 실패(red) 처리되지 않고 건너뜁니다.

라이선스

MIT. LICENSE를 참조하세요.