非公式 Google Trends MCP サーバー

⚠️ 非公式プロジェクトです。 Google とは提携しておらず、承認も支持もサポートも受けていません。Google Trends には一般的に利用可能な API が存在しないため、このサーバーは trends.google.com のウェブサイトが使っているのと同じ公開エンドポイントを（trendspy を介して）読み取ります。つまり、Google が予告なくいつでもレート制限をかけたり利用できなくしたりする可能性があります。自己責任でご利用いただき、利用にあたっては先に制限事項をお読みください。

Model Context Protocol サーバーで、AI アシスタント — Claude、ChatGPT、Cursor、または任意の MCP クライアント — に Google Trends データ（時系列の検索関心度、地域別の内訳、急上昇検索、キーワードのアイデア）へのアクセスを提供します。

リモート MCP サーバー（streamable HTTP）として動作し、Google Cloud Run 向けに設計されています。ご自身の Google Cloud プロジェクトでホストし、お好みの AI アシスタントに接続します。stdio 経由でローカルでも動作します。

好みの AI アシスタントに接続する

デプロイ後（セットアップ を参照）、https://<your-service>.run.app/<secret>/mcp のような形式のエンドポイント URL が得られます。すべてのツールは読み取り専用です。

Claude（Web/デスクトップ）: Settings → Connectors → Add custom connector と進み、URL を貼り付けます。Pro、Max、Team、Enterprise プランで利用できます。

ChatGPT（Web）: Developer mode を有効にします（Settings → Apps → Advanced settings）。次に Settings → Apps → Create で、MCP サーバーエンドポイントとして URL を貼り付け、認証なし（No authentication）を選択します（アクセス制御は URL に含まれるシークレットが担います）。Scan tools をクリック → Create。カスタム 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: Google Trends MCP Server

仕組み

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 インスタンス に制限されています。1 インスタンス = 1 つの IP と 1 つの共有キャッシュとなり、Google のレート制限を予測可能にします。アイドル時にはゼロにスケールするため、個人利用であればホスティング費用はほぼ無料です。

ツール

データバックエンド

データ層は差し替え可能です（backends/ 参照）。

• trendspy（デフォルト）— trendspy を使用します。これは Trends ウェブサイトと同じ非公式エンドポイントにアクセスします。無料で API キーは不要ですが、IP ごとにレート制限され、Google がエンドポイントを変更した場合に壊れる可能性があります。

• official（スタブ）— Google の公式 Trends API（アルファ版） 向けのもので、アプリケーション審査によるアクセス制限があります。Google からプロジェクトへのアクセスが許可されたら、backends/official_backend.py を設定し、TRENDS_BACKEND=official を設定してください。MCP ツールの契約は変わりません。

⚠️ Google Trends の値は 相対的な検索関心度（各クエリ内で 0〜100）であり、絶対的な検索ボリュームではありません。

セットアップ

ガイドは 2 つあります。ご自分のスキルに合わせて選んでください。

• 初心者向けガイド — ターミナルや Google Cloud を一度も使ったことがありませんか? ゼロからの完全チュートリアルで約 15 分です。

• 上級者向けガイド — 経験者ですか? クローン → ./deploy.sh → 接続。さらに、ローカル stdio モード、設定リファレンス、アーキテクチャのメモもあります。

Cloud Run へのデプロイ（クイック版）

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

このスクリプトは必要な API を有効化し、Cloud Build でコンテナをビルドし、スケール・トゥ・ゼロ（低使用量ならほぼ無料）でデプロイし、MCP エンドポイントを表示します:

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

ランダムな <secret> パスセグメントがアクセストークンです。サービス自体は技術的に公開されていますが、完全な URL がなければ到達できません。 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 はこの 2 つの「ウィジェット」エンドポイントについて、自動化（通常ブラウザ以外）クライアント向けにほぼゼロのクォータを設定しています。制限は IP ごとではなくクライアントのフィンガープリントごとであるため、プロキシや VPN やローカル実行でも回避できません。これらのツールはたいてい失敗せんことを気づいてください。エラーメッセージにその旨が表され、キーワード調査で信頼できる代替手段である keyword_ideas（Google Autocomplete）を案内します。

3. それ以外のエンドポイントにもレート制限があります。 動作しているエンドポイント（時系列・地域別・急上昇）にも IP 単位のレート制限があります。連続リクエストは HTTP 429 を引き起こします。サーバーの緩和策（下記）により通常利用ではまれですが、大量の自動クエリは壁にぶつかります。

4. 相対数値であり、ボリュームではありません。 Trends の数字はすべて 各クエリ内で 0〜100 です（100 = その語句の集合 / 期間のピーク）。絶対検索ボリュームではなく、別々のクエリ間で比較することはできません。

5. 鮮度とのトレードオフがあります。 レート制限内に収まるために結果はキャッシュされます（系列データ 12 時間、急上昇 15 分、オートコンプリート 24 時間）— 設計上、少しくすんだデータが表示されることがあります。

6. 単一インスタンスです。 --max-instances 1 でデプロイされるため、個人利用や小規模チーム向けであり、高コカレンシなプロダクション運用には向いていません。

レート制限と、サーバーがどのようにそれに対応しているか

Google は非公式の Trends エンドポイントにレート制限を適用します。サーバーはこれを層的な方法で緩和します。

• TTL キャッシュ — 同一のクエリはメモリから返され、（系列データは約 12 時間、急上昇は 15 分、オートコンプリートは 24 時間）Google に2回問い合わせることはありません。

• 間隔 + 囲み直列 — アップストリームへの呼び出しは同時に 1 件のみで、呼び出し間には TRENDS_REQUEST_DELAY（デフォルト 3 秒）の間隔を置きます。

• リトライ + サーキットブレーカー — 429 が返った場合に 1 回だけリトライし、その後 120 秒のクールダウンに入ります。クールダウン中は新しいクエリは即座に失敗し、「あと N 秒」と明確なメッセージを返すことで、Google を連打しません。キャッシュされたクエリはクールダウン中も動作し続けます。

• AI クライアントへの利用ルールの伝達 — MCP の指示書によってM CP の AI クライアントにルールを伝えます: interest_over_time 1 回の呼び出しで最大 5 語にまとめる、呼び出しをばら撒かではなく計画的に行う、レート制限エラーを自動リトライしない。

• related_queries / related_topics の現実 — Google はこれらの 2 つのウィジェットエンドポイントの自動化クライアント向けクォータをほぼゼロにしています。これはフィンガープリント単位のため、プロキシや IP 変更は効果がありません。失敗することを前提にしてください。エラーにはその旨が書かれています。キーワード調査には代わりに keyword科技 (= keyword_ideas (Google Autocomplete) を利用しましょう。高速かつ信頼性が高く、Trends のクォータに制約されません。

デプロイスクリプトの --max-instances 1 は意図的です。1 インスタンス = 1 つの IPと共有キャッシュ = 予測可能なレート制限です。

ヒント

1 語ずつ寻ねるのではなく、まとめて一度に比較をお願いしてください（「PT の過去 12 ヶ月間の A vs B vs C」→ 1 回の API 呼び出し）。最近聞いたものの繰り返しは（キャッシュにより）無料です。クールダウンのメッセージが表示されたら、指示された秒数だけ待ってください — リトライを連打しないでください。「X に関連する検索」を知りたい場合は、関連クエリではなくキーワードのアイデアを尋ねてください。

セキュリティに関する注意

このリポジトリに含まれるものはすべて汎用的です — 認証情報・キー・プロジェクトID・個人データはありません。このうち 2 つのことだけが あなたのマシン上のローカルのみに置き、決してコミットしてはいけません。

• .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 の承認も支持もサポートも受けていません。「Google Trends」および「Google」は Google LLC の商標であり、ソフトウェアが接続する対象を説明することでのみ使用しています。Trends データは公にアクセス可能なエンドポイントから取得されます。ご利用は Google の利用規約に合わせて自己責任で行ってください。いかなる保証もありません — エンドポイントはいつでも停止する可能性があります。

ライセンス

MIT

MIT