비공식 Google Trends MCP 서버

⚠️ 비공식 프로젝트입니다. Google과 제휴하거나 보증 또는 지원을 받지 않습니다. Google Trends에는 일반에 공개된 공식 API가 없으므로, 이 서버는 trends.google.com 웹사이트가 사용하는 것과 동일한 공개 엔드포인트를 (trendspy를 통해) 읽습니다. 즉, Google이 사전 통지 없이 언제든지 속도 제한을 걸거나 차단할 수 있습니다. 사용에 따른 책임은 본인에게 있으며, 의존하기 전에 제한 사항을 반드시 읽어보세요.

AI 어시스턴트 — Claude, ChatGPT, Cursor 또는 모든 MCP 클라이언트 — 에게 Google Trends 데이터(시간별 검색 관심도, 지역별 분석, 인기 검색어, 키워드 아이디어)에 대한 액세스를 제공하는 Model Context Protocol 서버입니다.

원격 MCP 서버(streamable HTTP)로 실행되며 Google Cloud Run용으로 설계되었습니다. 사용자가 자신의 Google Cloud 프로젝트에 호스팅하고 원하는 AI 어시스턴트에 연결합니다. stdio를 통한 로컬 실행도 가능합니다.

AI 어시스턴트에 연결하기

배포( 설정 참조) 후에는 https://<your-service>.run.app/<secret>/mcp 형식의 엔드포인트 URL이 생성됩니다. 모든 도구는 읽기 전용입니다.

Claude(웹/데스크톱): 설정 → 커넥터 → 사용자 지정 커넥터 추가 → URL 붙여넣기. Pro, Max, Team, Enterprise 요금제에서 작동합니다.

ChatGPT(웹): 개발자 모드 활성화(설정 → 앱 → 고급 설정) 후 설정 → 앱 → 만들기에서 URL을 MCP 서버 엔드포인트로 붙여넣고, 인증 없음을 선택합니다(액세스 제어는 URL의 시크릿 경로가 담당). 도구 스캔 클릭 → 만들기. 사용자 지정 MCP 커넥터는 유료 요금제가 필요하며, Pro에서는 커넥터가 읽기 전용 도구로 제한됩니다 — 이 서버는 전부 읽기 전용이므로 문제없이 작동합니다.

Claude Code / Cursor / 기타 MCP 클라이언트: streamable HTTP를 통한 원격 MCP를 지원하는 모든 클라이언트가 작동합니다(예: claude mcp add --transport http google-trends <URL>). 로컬/stdio 설정은 docs/setup-advanced.md를 참조하세요.

Related MCP server: youtube-trends-mcp

작동 방식

AI assistant (Claude · ChatGPT · Cursor · any MCP client)
   │  MCP over streamable HTTP, at https://<cloud-run-url>/<secret>/mcp
   ▼
server.py — FastMCP tool layer (stateless, JSON responses)
   │  TrendsBackend interface (swappable, see backends/)
   ▼
backends/trendspy_backend.py
   │  1. TTL cache — identical queries answered from memory
   │     (12 h series · 15 min trending · 24 h autocomplete)
   │  2. Circuit breaker — after a 429: cooldown, fail fast with
   │     a clear "retry in Ns" message (no hammering Google)
   │  3. One upstream call at a time, ≥3 s apart
   ▼
Google's public endpoints
   ├─ trends.google.com (unofficial, same as the website uses)
   └─ suggestqueries.google.com (Autocomplete, for keyword_ideas)

액세스 제어는 URL의 무작위 시크릿 경로 세그먼트(배포 시 생성되며 gitignore된 .mcp_secret 파일에 저장)로 이루어집니다. 대부분의 채팅 클라이언트 사용자 지정 커넥터 UI(Claude, ChatGPT)가 인증 헤더를 보낼 수 없기 때문입니다. Cloud Run 서비스는 의도적으로 단일 인스턴스로 제한됩니다. 인스턴스 1개 = IP 1개 + 공유 캐시 1개로, Google의 속도 제한을 예측 가능하게 유지합니다. 유휴 시 0으로 스케일링되므로 개인 사용 수준에서는 호스팅 비용이 거의 무료입니다.

도구

데이터 백엔드

데이터 계층은 교체 가능합니다(backends/ 참조):

• trendspy (기본값) — trendspy를 사용하며, Trends 웹사이트와 동일한 비공식 엔드포인트에 연결합니다. 무료이고 API 키가 필요 없지만 IP당 속도 제한이 있으며 Google이 엔드포인트를 변경하면 작동이 중단될 수 있습니다.

• official (스텁) — 애플리케이션 게이트 방식인 Google 공식 Trends API(알파)용입니다. Google이 프로젝트에 액세스 권한을 부여하면 backends/official_backend.py를 연결하고 TRENDS_BACKEND=official로 설정하세요. MCP 도구 계약은 동일하게 유지됩니다.

⚠️ Google Trends의 값은 상대적 검색 관심도(각 쿼리 내에서 0–100)이며 절대 검색량이 아닙니다.

설정

두 가지 가이드가 있습니다. 속도에 맞게 선택하세요:

• 초보자 가이드 — 터미널이나 Google Cloud를 사용해 본 적이 없나요? 처음부터 끝까지 전체 안내, 약 15분 소요.

• 고급 가이드 — 경험이 있나요? 클론 → ./deploy.sh → 연결; 로컬 stdio 모드, 구성 참조, 아키텍처 노트 포함.

Cloud Run에 배포(빠른 버전)

gcloud auth login
./deploy.sh YOUR_PROJECT_ID europe-west1

스크립트는 필요한 API를 활성화하고, Cloud Build로 컨테이너를 빌드하고, scale-to-zero(낮은 사용량에서 거의 무료)로 배포한 후 MCP 엔드포인트를 출력합니다:

https://google-trends-mcp-xxxxx.a.run.app/<secret>/mcp

무작위 <secret> 경로 세그먼트가 액세스 토큰입니다. 서비스는 기술적으로 공개되어 있지만 전체 URL 없이는 접근할 수 없습니다. 비밀로 유지하고, 새 시크릿으로 재배포하여 교체하세요.

AI 어시스턴트 연결

Claude와 ChatGPT는 위의 AI 어시스턴트에 연결하기를 참조하세요. Claude Code:

claude mcp add --transport http google-trends https://google-trends-mcp-xxxxx.a.run.app/<secret>/mcp

로컬 실행

pip install -r requirements.txt
python server.py
# MCP endpoint at http://localhost:8080/mcp

구성

제한 사항 및 알려진 문제

이 서버에 의존하기 전에 반드시 읽어보세요 — 이는 버그가 아니라 구조적인 문제입니다:

1. 비공식 데이터 소스. 공개 Google Trends API가 없습니다(Google의 공식 API는 알파 버전이며 초대 전용). 이 서버는 웹사이트 자체 엔드포인트를 사용하므로 Google이 언제든지 변경하거나 차단할 수 있습니다. Google이 무언가를 변경하면 trendspy가 따라잡을 때까지 서버가 중단됩니다 — 2025년에 이전 pytrends 라이브러리에서 정확히 이런 일이 발생했습니다.

2. related_queries 및 related_topics는 사실상 사용 불가입니다. Google은 자동화된(비브라우저) 클라이언트에 대해 이 두 "위젯" 엔드포인트의 할당량을 거의 0으로 제한합니다. 제한은 IP가 아닌 클라이언트 지문(fingerprint)별로 적용되므로 프록시, VPN, 로컬 실행도 도움이 되지 않습니다. 대부분의 경우 첫 호출에서 실패할 것으로 예상하세요. 오류 메시지에 그 이유가 설명되어 있으며 키워드 리서치의 안정적인 대안인 keyword_ideas(Google 자동 완성)를 안내합니다.

3. 다른 모든 것에 대한 속도 제한. 작동하는 엔드포인트(시간별 관심도, 지역별, 인기 급상승)도 IP당 속도 제한이 있습니다. 요청이 폭주하면 HTTP 429가 발생합니다. 서버의 완화 조치(아래 참조)로 일반적인 사용에서는 드물지만, 대량의 자동화된 쿼리는 한계에 부딪힙니다.

4. 상대적 값이지 볼륨이 아닙니다. 모든 Trends 숫자는 각 쿼리 내에서 0–100입니다(100 = 해당 용어 세트/기간/지역의 최고치). 절대 검색량이 아니며 서로 다른 쿼리 간에 비교할 수 없습니다.

5. 최신성 트레이드오프. 속도 제한을 유지하기 위해 결과가 캐시됩니다(시계열 데이터 12시간, 인기 급상승 15분, 자동 완성 24시간) — 의도적으로 약간 오래된 데이터가 표시될 수 있습니다.

6. 단일 인스턴스. --max-instances 1로 배포되므로 개인/소규모 팀용이며, 높은 동시성을 요구하는 프로덕션 트래픽용이 아닙니다.

속도 제한 및 이를 고려한 서버 설계

Google은 비공식 Trends 엔드포인트에 속도 제한을 적용합니다. 서버는 이를 계층적으로 완화합니다:

• TTL 캐시 — 동일한 쿼리는 메모리에서 제공되며(시계열 데이터 약 12시간, 인기 급상승 15분, 자동 완성 24시간) Google에 두 번 요청하지 않습니다.

• 간격 + 직렬화 — 한 번에 하나의 업스트림 호출, 호출 사이에 TRENDS_REQUEST_DELAY 지연(기본 3초).

• 재시도 + 회로 차단기 — 429 발생 시 한 번의 온건한 재시도 후 쿨다운(120초) 동안 새 쿼리는 Google을 두드리는 대신 "N초 후 재시도"라는 명확한 메시지와 함께 빠르게 실패합니다. 캐시된 쿼리는 쿨다운 중에도 계속 작동합니다.

• 사용 규칙을 MCP 지침을 통해 AI 클라이언트에 전달 — interest_over_time 호출당 최대 5개 용어 일괄 처리, 무분별한 호출 대신 계획된 호출, 속도 제한 오류 시 자동 재시도 금지.

• related_queries / related_topics 현실: Google은 자동화된(비브라우저) 클라이언트에 대해 이 두 위젯 엔드포인트의 할당량을 거의 0으로 줄였습니다 — 이는 지문별 제한이므로 프록시와 IP 변경도 도움이 되지 않습니다. 실패할 것으로 예상하세요. 오류에 설명이 있습니다. 키워드 리서치에는 keyword_ideas(Google 자동 완성)를 대신 사용하세요 — 빠르고 안정적이며 Trends 할당량에 묶이지 않습니다.

배포 스크립트의 --max-instances 1은 의도적입니다: 인스턴스 1개 = IP 1개 + 공유 캐시 1개 = 예측 가능한 속도 제한.

사용자 팁

한 번에 하나씩 묻지 말고 한 번에 비교를 요청하세요("PT에서 12개월 동안 A vs B vs C 비교" → API 호출 1회). 최근 질문의 반복은 캐시로 처리되어 무료입니다. 쿨다운 메시지가 표시되면 표시된 시간만 기다리세요 — 재시도를 남발하지 마세요. "X 주변에서 사람들이 무엇을 검색하나"는 관련 검색어 대신 키워드 아이디어를 요청하세요.

보안 참고 사항

이 저장소의 모든 것은 일반적입니다 — 자격 증명, 키, 프로젝트 ID 또는 개인 데이터가 없습니다. 두 가지만 사용자 머신에 로컬로 유지되며 절대 커밋해서는 안 됩니다:

• .mcp_secret — 엔드포인트 URL의 무작위 문자열입니다. 배포된 서버에 낯선 사람이 접근하는 것을 막는 유일한 수단이므로 비밀번호처럼 취급하세요. deploy.sh는 첫 실행 시 이를 생성하고 여기에 보관하여 재배포 시 동일한 URL을 재사용합니다. gitignore되어 있습니다. (GitHub와는 무관합니다 — GitHub 토큰이 아니며 계정에 대한 액세스 권한이 없습니다.)

• Google Cloud 프로젝트 ID — deploy.sh에 명령줄 인수로 전달되며 저장소의 어떤 파일에도 기록되지 않습니다.

시크릿을 교체하려면(예: URL이 유출된 경우): .mcp_secret을 삭제하고 ./deploy.sh <PROJECT_ID>를 다시 실행한 다음 AI 어시스턴트의 커넥터 설정에서 URL을 업데이트하세요. 이전 URL은 즉시 작동이 중단됩니다.

첫 푸시 전에 민감한 내용이 스테이징되지 않았는지 확인하세요:

git status --short          # .mcp_secret and .env must NOT appear
git check-ignore -v .mcp_secret

고지 사항

비공식 커뮤니티 프로젝트입니다. Google과 제휴하거나 보증 또는 지원을 받지 않습니다. "Google Trends" 및 "Google"은 Google LLC의 상표이며, 소프트웨어가 연결하는 대상을 설명하는 용도로만 사용됩니다. Trends 데이터는 공개적으로 접근 가능한 엔드포인트를 통해 가져오며, Google의 서비스 약관에 부합하게 사용할 책임은 사용자에게 있으며 사용에 따른 위험은 사용자가 감수합니다. 어떠한 종류의 보증도 없습니다 — 엔드포인트는 언제든지 작동이 중단될 수 있습니다.

라이선스

MIT