seo-analytics-mcp

Google Search Console、GA4、IndexNow — MCPサーバーとして。

Claudeに自分のサイトについて尋ねましょう。何がランキングに入っているか、何が変わったか、何がインデックスされているか、何がコンバージョンにつながっているか。

"Which pages lost the most clicks in the last 28 days versus the 28 before?"
"How is /pricing doing?"
"Is https://example.com/new-post indexed yet?"
"Which pages rank on page one but get almost no clicks?"
"Top 20 queries for the blog last month, and which of them convert in GA4."

ご自身のGoogleアカウントを、ご自身のGoogle Cloudプロジェクト内のOAuthクライアントに対して認証します。あなたのアクセスが第三者を経由することは一切なく、このリポジトリには認証情報は含まれず、消費するGoogleクォータはすべてあなた自身のものです。

目次

インストール · セットアップ · 7日間の問題 · ツール · レスポンスの形式 · 設定 · 書き込み · プロファイル · 設計 · トラブルシューティング · 開発

Related MCP server: GSC Analyst Connector

インストール

Python 3.10以上とuvが必要です。

uvx seo-analytics-mcp doctor      # no install needed — prints your setup steps, in order

doctorはオンボーディング体験全体を担います。各段階で、何が不足していて次に何を実行すべきかを正確に教えてくれます。ここで他に何も読まないとしても、これを実行してください。

セットアップ

Google Cloudコンソールでの6クリック、それから1コマンド。一度だけ、10分です。

Google Cloudプロジェクトを作成 — または既存のものを再利用。 console.cloud.google.com/projectcreate

APIを有効化。 Search Consoleは必須。GA4の2つは任意です。

searchconsole · analyticsdata · analyticsadmin

同意画面を設定し、アプリを公開を押す。 console.cloud.google.com/auth/overview

外部を選択して公開します。あなたは自分のアプリの唯一のユーザーなので、Googleの個人利用の例外が適用され、審査は不要です。Workspaceユーザーは代わりに内部を選択できます。

公開ステップをスキップしないでください — 下記を参照。

種類デスクトップアプリのOAuthクライアントを作成し、JSONをダウンロード。 console.cloud.google.com/auth/clients

ウェブアプリケーションクライアントでは、このサーバーが必要とするループバックリダイレクトができません。doctorはこの特定のミスをチェックします。なぜなら、これが最も犯しやすいミスだからです。

ターミナルから一度だけ認証:

uvx seo-analytics-mcp auth --client-secret ~/Downloads/client_secret_*.json

ブラウザが開きます。Googleが*「Google hasn't verified this app」*と表示します — 自分のクライアントでは想定どおりです: 詳細 → 続行。トークンはプロファイルディレクトリにモード0600で保存されます。

確認して、接続:

uvx seo-analytics-mcp doctor      # eleven checks; exit 0 means it will work

接続する

claude mcp add seo \
  -e GSC_DEFAULT_SITE=sc-domain:example.com \
  -e GA4_DEFAULT_PROPERTY=properties/123456789 \
  -- uvx seo-analytics-mcp

{
  "mcpServers": {
    "seo": {
      "command": "uvx",
      "args": ["seo-analytics-mcp"],
      "env": {
        "GSC_DEFAULT_SITE": "sc-domain:example.com",
        "GA4_DEFAULT_PROPERTY": "properties/123456789"
      }
    }
  }
}

その後、Claude Desktopを完全に終了し（⌘Q — ウィンドウを閉じるだけでは不十分）再起動します。

[!NOTE] その設定には認証情報のパスはありません。トークンはseo-mcp authが書き込んだプロファイルディレクトリに存在するため、ブロック全体をGitHubのissueに貼り付けても安全です。

7日間の問題

[!WARNING] サーバーが動作してから約1週間後に停止した場合、これが原因です。

Googleは、公開ステータスがまだテストのままの外部OAuthアプリに対して、7日後に期限切れになるリフレッシュトークンを発行します。プロジェクト作成 → クライアント作成 → 自分をテストユーザーとして追加、という一見明白なセットアップ手順では、そこに留まってしまいます。

修正は1クリックです: 同意画面で、オーディエンスを外部に設定してアプリを公開を押します。その後uvx seo-analytics-mcp auth --reauthを実行します。

doctorは、まだテスト用トークンである可能性のある新しいトークンを検出し、サーバーからのすべてのinvalid_grantエラーはこれを完全に説明します。これはサーバーのバグではありません — しかし、最も多く報告される問題になるでしょう。

ツール

13のツール: 10は上流の操作に対応し、2つはソースを結合し、1つはモデルが混乱したユーザーに何をすべきか伝えるためだけに存在します。

レスポンスの形式

すべての読み取りツールは同じ4つのキーを返します。境界があり、自己記述的で、独自の注意事項を伴います。

{
  "summary": {
    "source": "gsc",
    "rows_returned": 10,        // what you see
    "rows_matched": 1847,       // what exists upstream
    "date_range": "2026-07-29..2026-08-25",   // resolved, always echoed
    "data_state": "final",
    "totals": { "clicks": 4730, "impressions": 512903, "ctr": 0.0092, "position": 12.4 }
  },
  "rows": [ /* capped at min(row_limit, 1000) */ ],
  "notes": [
    "Google anonymises rare queries: these rows do NOT sum to property totals.",
    "dataState=final excludes the most recent 2-3 days.",
    "1837 further rows were not included inline."
  ],
  "export": "~/.../exports/a1b2c3.csv"        // only when rows spilled
}

どこでも共通する3つの規約:

合計は表示された行だけでなく、取得したすべての行をカバーします — 10行と10行分の合計を見たモデルは、切り詰めと現実を区別できません。レートは決して平均化されません: ctrはクリック数 ÷ インプレッション数から再計算され、positionはインプレッション加重、engagementRateはエンゲージ済み ÷ セッションです。

注意事項はデータとともに移動します。 注意事項を知っているレイヤーがそれを追加します: クライアントはqueryディメンションが要求されたことを知っており、shape()は何行を破棄したかを知っており、GA4はレスポンスがサンプリングされたことを知っています。docstringだけでは、モデルが数値を見ているまさにその時に注意事項が失われます。

エラーは修正方法を示します。 403はどの権限を確認すべきか、どこで確認すべきかを示します — 生のGoogleエラーボディは決して返しません。

The authorised Google account has no access to sc-domain:example.com. Confirm the
account you authorised is the one with access — Search Console grants are per-property
under Settings > Users and permissions, GA4 grants are per-property under Admin >
Property access management. If access was added recently, run `seo-mcp auth --reauth`.

設定

すべての変数は任意です。優先順位: ツール引数 → 環境変数 → プロファイルconfig.json。

日付

すべての日付引数はYYYY-MM-DD、today、yesterday、NdaysAgoを受け付けます。レスポンスは実際に使用した絶対的な範囲をエコーします。なぜなら、モデルが今日の日付を間違って推測すると、*「トラフィックがゼロになった」*と読める空の結果が生成されるからです。

Search Consoleは2〜3日の遅延があり、約16か月分を保持します。これらの範囲外の期間は、黙って何も返さずにフラグを立てるか拒否されます。GA4はプロパティ自身のタイムゾーンでレポートするため、その日付はSearch Consoleのものと正確には一致しません — レスポンスは重要箇所でその旨を明示します。

書き込み

2つのツールがあなたのマシンの外の世界に作用します。どちらも意図的に扱いにくくしています。

[!IMPORTANT] confirmフラグだけでは安全機構にはなりません — これはモデルが入力する引数であり、誤ったURLを生成するのと同じ誤読が、その隣にconfirm=trueも生成します。

トークンはドライランなしでは偽造できず、1つのURLを変更すると一致しなくなります。両方のツールはdestructiveHintアノテーションも持つため、破壊的ツールを独自の承認プロンプトの背後にゲートするクライアントは、そのように動作します。

読み取り専用スコープがデフォルトです。見知らぬ人が、Search Consoleプロパティの変更権限をすぐに要求するSEOツールをインストールするのを、合理的に拒否するでしょう。

プロファイル

1台のマシンで複数のGoogleアカウント — クライアントのプロパティを並行して管理する代理店向け。

uvx seo-analytics-mcp auth --profile client-a --client-secret ./client-a.json
uvx seo-analytics-mcp auth --profile client-b --client-secret ./client-b.json
uvx seo-analytics-mcp profiles list

MCPサーバーエントリごとにSEO_MCP_PROFILEを設定します。キャッシュキーにはプロファイルが含まれるため、2つのアカウントが互いのデータを提供することは決してありません。

プロファイルは1つのディレクトリです — ユーザーに削除を依頼する最初のものになるでしょう:

uvx seo-analytics-mcp profiles rm client-a --yes

これらは~/Library/Application Support/seo-mcp/（macOS）、$XDG_CONFIG_HOME/seo-mcp/（Linux）、または%APPDATA%\seo-mcp\（Windows）にあります。

設計

4つのレイヤー、厳密に下向き。これを間違えると、認証フローがツール呼び出しの中に入り込んでしまいます。これは、この設計全体が防ごうとしている失敗です。

flowchart TD
    subgraph L4["Entry points"]
        S[server.py<br/><i>MCPServer, stdio</i>]
        C[cli.py<br/><i>auth · doctor · profiles · serve</i>]
    end
    subgraph L3["Tools — argument surface, docstrings, cache policy"]
        T[13 handlers<br/><i>no HTTP, no credentials, no row shaping</i>]
    end
    subgraph L2["Clients — the only modules that speak HTTP"]
        G[gsc.py]
        A[ga4.py]
        I[indexnow.py]
    end
    subgraph L1["Leaves — importable by anyone, import nobody"]
        LV[shaping · errors · config · cache · auth/store · auth/scopes]
    end
    F[auth/flow.py<br/><i>loopback + PKCE · opens a browser</i>]

    S --> T
    C --> T
    C -.->|only reachable from here| F
    T --> G & A & I
    G & A & I --> LV

ブラウザフローはツール呼び出し内で決して実行してはなりません。 人間が同意画面を完了するのを待つためにstdioでブロックするMCPツールは、ハングしたサーバーのように見え、モデルは助ける方法がありません。一度だけ実行する1つのCLIコマンドがすべての違いです — そしてテストがすべてのモジュールのASTを走査してこれを強制します。

テストが機械的に強制する他のルール: shaping.pyはGoogleライブラリをインポートせず（そのため行ロジックは認証情報なしで完全にユニットテスト可能）、ツールはHTTPライブラリをインポートせず、サーバーパス上の何もprint()を呼び出しません — stdioトランスポートでは、stdoutはJSON-RPCを運び、1つの迷いprintがストリームを破壊します。

トラブルシューティング

すべての不具合報告にはseo-mcp doctor --jsonを含める必要があります。 認証情報は含まれず、パス、バージョン、合格したチェック、応答したAPIのみが含まれます。

開発

uv sync --extra dev
uv run pytest -q                    # 147 tests · no credentials · no network
uv run python scripts/smoke.py      # drives the server over real stdio JSON-RPC
uv run ruff check src tests

python3 -m venv .venv && ./.venv/bin/pip install -e ".[dev]"
./.venv/bin/python -m pytest -q
./.venv/bin/python scripts/smoke.py ./.venv/bin/seo-mcp

scripts/smoke.pyはサーバーをサブプロセスとして起動し、MCPハンドシェイクを完了し、ツールを一覧表示して複数のツールを呼び出します — 使い捨てのプロファイルディレクトリを使用するため、実際のトークンには触れません。Googleの認証情報が存在する前にプロトコル側が動作することを確認する最速の方法です。

手動で試す場合、MCP InspectorはNodeだけで十分です：

npx @modelcontextprotocol/inspector ./.venv/bin/seo-mcp            # web UI
npx @modelcontextprotocol/inspector --cli ./.venv/bin/seo-mcp \
    --method tools/call --tool-name auth_status                    # scriptable

自動テストの対象外： OAuthフロー自体と実際のIndexNow送信。どちらも人間と実際のドメインが必要であり、モック化してもモックをテストするだけです。これらは短い手動リリースチェックリストに含めるべきです。

できない2つのこと

[!NOTE] IndexNowはGoogleには届きません。 参加者はBing、Yandex、Naver、Seznam.cz、Yep、Amazonで、1つのエンドポイントがそれらすべてに伝播します。Googleは参加しておらず、Google独自のIndexing APIはJobPostingまたはBroadcastEventの構造化データを含むページのみを受け入れます。Googleのインデックスが速くなることを期待してこれをインストールすると、がっかりするでしょう。

[!NOTE] クエリ行の合計は総数と一致しません。 Googleはまれなクエリを匿名化するため、queryディメンションによる内訳は過小計上になります。そのディメンションを含むすべてのレスポンスはこの注意事項を繰り返します。なぜなら、その行を渡されたモデルは、そうでなければ誤ったパーセンテージを自信を持って計算してしまうからです。

コントリビューション

Issueとプルリクエストを歓迎します。認証情報不要のテストスイートは、Python 3.10と3.13でLinux、macOS、Windowsのすべてのプッシュで実行されます — ローカルで合格すればCIでも合格します。

ツールの名前を変更したり引数を変更したりすると、ユーザーが保存したすべてのプロンプトが壊れます。そのような変更はCHANGELOG.mdに記載され、1.0より前ではマイナーバンプ、1.0以降ではメジャーバンプになります。

ライセンス

MIT。