Google Trends MCP

로컬 MCP 서버로, Claude(또는 모든 MCP 클라이언트)가 Google Trends를 직접 조회할 수 있게 해 줍니다 — 시간에 따른 검색 관심도, 연관 검색어와 주제, 지역별 분석, 실시간 인기 급상승 검색어 — 그래서 trends.google.com으로 탭을 전환하고 스크린샷을 다시 붙여넣는 대신 대화 속에서 시장 조사를 수행할 수 있습니다.

개인적/자기 활용 목적의 시장 조사를 위해 만들어졌습니다. API 키가 필요 없습니다 — Google Trends에는 공식 공개 API가 없으므로, 이 서버는 표준 비공식 Python 클라이언트인 pytrends를 MCP 서버로 감싼 것입니다.

도구

명시되지 않는 한 모든 도구는 기본적으로 geo="IN"(인도)을 사용합니다. 전 세계를 대상으로 하려면 geo=""을 전달하거나, ISO 국가 코드("US", "GB" 등)를 전달하세요. timeframe은 pytrends의 형식을 받으며, 예를 들어 "today 12-m", "today 5-y", "now 7-d" 또는 명시적 기간 범위 "2024-01-01 2024-06-01"을 사용할 수 있습니다.

interest_over_time(keywords, timeframe="today 12-m", geo="IN")

최대 5개 키워드에 대한 시간대별 상대적 검색 관심도(0–100)를 나란히 비교해 보여 줍니다. 처음 5개를 초과하는 키워드는 조용히 무시됩니다. 각 레코드에는 isPartial이 포함됩니다. 가장 최근 데이터 지점에서 true가 나오면 그 기간이 아직 끝나지 않았으며 해당 값은 잠정적이라는 뜻입니다. 그 지점의 하락을 실제 추세 변화로 읽지 마십시오.

related_queries(keyword, timeframe="today 12-m", geo="IN")

단일 키워드에 대한 인기 연관 검색어와 급상승 연관 검색어를 보여 줍니다. {"top": [...], "rising": [...]}을 반환하며, 각각은 {"query": ..., "value": ...} 레코드 목록입니다. top 값은 0–100의 상대적 관심도입니다. rising 값은 증가율(백분율)입니다 — 단, 5000%는 예외인데, 이는 거의 0에 가까운 베이스라인에서 폭발적으로 증가했다는 Google의 "Breakout" 마커이지 실제 백분율이 아닙니다.

related_topics(keyword, timeframe="today 12-m", geo="IN")

related_queries와 동일하지만, 원본 검색어 문자열 대신 주제 클러스터(Google 자체 주제 그룹)로 보여 줍니다 — 레코드에는 value와 함께 topic_title과 topic_type이 있습니다. rising에도 동일한 Breakout 규칙이 적용됩니다.

interest_by_region(keyword, timeframe="today 12-m", geo="IN")

주어진 geo 내에서 키워드의 검색 관심도를 주/지역별로 나눠 보여 줍니다. 지역별로 하나씩 {"geoName": ..., "<keyword>": 0-100} 레코드 목록을 반환합니다.

trending_now(geo="india")

오늘 한 국가에서 가장 많이 오르found 않은 인기 검색어를 보여 줍니다. 여기서 geo 형식은 다르다는 점에 유의하세요. — 다른 네 도구와 달리 ISO 코드가 아니라 전체 소문자 국가 이름("india", "united_states")을 사용합니다. 이는 버그가 아니라 Google 자체 엔드포인트에 실제로 있는 불일치입니다입니다.

알려진 제한 사항: 현재 시점에서 trending_now는 HTTP 404로 실패합니다. Google은 pytrends의 급상승 검색 메서드들이 의존하던 기존 엔드포인트(hottrends/dailytrends/realtimetrends)를 폐지한 것으로 보이며, pytrends가 제공하는 세 가지 변형을 모두 테스트해 본 결과입니다. 이는 업스트림 문제이므로 이 코드베이스에서 해결할 수 없습니다. 크래시하는 대신, 읽을 수 있는 오류 문자열을 반환하며 깔끔하게 실패합니다. 나머지 4개 도구는 여전히 작동하는 다른 엔드포인트 계열을 사용하므로 영향을 받지 않습니다. Google이 엔드포인트를 복원하거나 pytrends가 이에 대응해 패치를 제공하면, 이 코드를 수정할 필요 없이 다시 작동할 것입니다.

모든 도구는 실패(호출 횟수 제한, 네트워크 오류, 위 사례)를 잡아내고 크래시하지 않는 대신 일반 오류 문자열을 반환합니다. Google Trends는 안정적인 API가 아니라 스크래핑 대상 엔드포인트이므로, 이는 예외 상황이 아니라 예상되는 동작입니다.

설정

Python 3.10+ 및 uv가 필요합니다.

git clone https://github.com/jain-eshan/google-trends-mcp.git
cd google-trends-mcp
uv sync

Claude Code에 등록

claude mcp add google-trends -- uv run --directory /absolute/path/to/google-trends-mcp server.py

연결이 되었는지 확인합니다:

claude mcp list

google-trends가 ✔ Connected로 표시되는지 확인합니다. 등록 후에는 새 Claude Code 대화를 시작하세요. 이미 실행 중인 세션은 새로 추가된 서버를 인식하지 못합니다.

사용법

등록 후에는 Claude에서 자연스럽게 사용하도록 요청하면 됩니다. 예:

"google-trends MCP를 사용해 지난 12개월 동안 인도에서 'lab grown diamonds' vs 'diamond jewellery'에 대한 관심를 비교해 주고, 연관 검색어가 무엇인지 보여 줘."

선택 사항: /trends 스킬

이 저장소에는 .claude/skills/trends/SKILL.md에 Claude Code 스킬이 포함되어 있어, 원본 도구들을 "조사 후 종합"하는 작업 흐름으로 감쌉니다. 이 스킬은 사용자 주제와 관련된 도구를 스스로 결정하고, raw JSON을 그대로 출력하는 대신 일상 언어로 된 요약을 작성해 줍니다. Claude Code를 사용하고 있다면 이 스킬은 이 저장소에서 자동으로 인식됩니다. 다음 명령만 실행하면 됩니다:

/trends <your topic>

설계 메모

• 서버에는 데이터만 있고, 종합은 없습니다. 모든 도구는 하우징되지 않은 구조화된 데이터를 반환합니다 — 이 추세가 실제인지, 여기서 Breakout 마커가 무엇을 의미하는지, 무엇을 집어 짚을 가치가 있는지의 해석은 서버에 내장되는 것이 아니라 호출하는 대화에서 일어납니다. 이렇게 하면 서버가 단순해진 유지만 되고, 호출하는 쪽(Claude이든 다른 MCP 클라이언트이든)이 스스로 판단할 수 있습니다.

• mcp[cli]와 pytrends 외에는 의존성이 없습니다. 데이터베이스도, 설정 파일도, API 키도 없습니다.

• 정식 테스트 스위트대상 없습니다. 이 서버는 스크래핑된 서드파티 엔드포인트를 감싼 것이라, 테스트 스위트가 있다면 주로 이 코드보다는 pytrends와 Google의 현재 응답 형태를 테스트하게 될 것입니다. 개발 중에 각 도구는 실제 Google Trends 데이터로 검증했습니다.

라이선스

MIT — LICENSE를 참조하세요.