gsc-ga4-mcp

Claude Code に Google Search Console と GA4 への読み取り専用アクセスを提供する、小さなローカル MCP サーバーです。さらに、これら 2 つのデータセットを横断するいくつかのツールも含まれます。

問題

AI アシスタントでの SEO 作業は、通常、Search Console から CSV をエクスポートし、GA4 からも CSV をエクスポートし、両方をチャットに貼り付けることを意味します。そして、新しい数字が欲しくなるたびに同じことを繰り返します。また、2 つのデータセットは自動的には対応しません。Search Console はインプレッション、クリック数、CTR を把握し、GA4 はセッション、エンゲージメント、コンバージョンを把握します。「トラフィックはあるのに無駄にしているページ」を特定するには、URL で手動で結合する必要があります。

Google は Analytics 向けの公式 MCP サーバーを公開していますが、Search Console には対応していません。コミュニティ製の Search Console サーバーもありますが、データがクライアントのものである場合、他者のサーバーを信頼するより、全体を読み取れる小さなラッパーを自分で実行する方が良いでしょう。

このサーバーは、公式の Google API を読み取り専用スコープで、自分のマシンから直接呼び出します。

Related MCP server: Google Search Console MCP Server

機能

stdio で動作する MCP ツールが 20 個あります。

Search Console

GA4

複合分析

構成

project_mappings と project_lookup は、プロジェクト名やクライアント名を GSC プロパティと GA4 プロパティに対応付けるローカルファイルを読み取ります。これにより、properties/123456789 を覚えて使う代わりに、「example.com の GSC と GA4 を掛け合わせて」という指示ができます。

スタック

Node.js + TypeScript。サーバ部は @modelcontextprotocol/sdk、認証は google-auth-library、ツールスキーマは zod。データベースなし、ホスティングバックエンドなし、テレメトリなし。プロセスはローカルで実行され、Claude Code が stdio を介して起動します。

スコープは読み取り専用で、これが権限の全容です。

• https://www.googleapis.com/auth/webmasters.readonly

• https://www.googleapis.com/auth/analytics.readonly

認証情報はリポジトリの外に置き、既定では ~/.config/gsc-ga4-mcp/ に保存されます。

セットアップ

1. インストール

git clone https://github.com/YOUR_USER/gsc-ga4-mcp.git
cd gsc-ga4-mcp
npm install
npm run build
mkdir -p ~/.config/gsc-ga4-mcp

2. API を有効にする

Google Cloud Console でプロジェクトを作成または選択し、次を有効にします。

• Google Search Console API

• Google Analytics Data API

• Google Analytics Admin API

3. OAuth 認証情報を作成する

API とサービス → OAuth 同意画面 で、同意画面を設定します。管理しているプロパティが 1 つの Google Workspace にすべて入っていなければ、外部（External）を選択し、アプリがテスト中は自分のメールアドレスをテストユーザーに追加します。

API とサービス → 認識情報 で、種類を デスクトップ アプリ に指定して OAuth クライアント ID を作成し、JSON をダウンロードして ~/.config/gsc-ga4-mcp/oauth-client.json として保存します。

クライアントごとに権限を分離したい場合は、代わりにサービスアカウントを使い、そのメールアドレスを読み取りアクセス権を持つ各 GSC プロパティと GA4 プロパティに追加します。GOOGLE_AUTH_MODE=service_account を設定し、GOOGLE_SERVICE_ACCOUNT_KEY_FILE にキーを指定します。

4. 設定

cp .env.example .env
cp projects.example.json ~/.config/gsc-ga4-mcp/projects.json

.env 内のパスは絶対パスにする必要があります。~ は展開されません。

GOOGLE_AUTH_MODE=oauth
GOOGLE_OAUTH_CREDENTIALS_FILE=/Users/YOUR_USER/.config/gsc-ga4-mcp/oauth-client.json
GOOGLE_TOKEN_PATH=/Users/YOUR_USER/.config/gsc-ga4-mcp/token.json
GOOGLE_OAUTH_REDIRECT_URI=http://127.0.0.1:3000/oauth2callback
PROJECTS_CONFIG=/Users/YOUR_USER/.config/gsc-ga4-mcp/projects.json
MCP_DEFAULT_GSC_SITE=sc-domain:example.com
MCP_DEFAULT_GA4_PROPERTY=properties/123456789
MAX_ROWS=25000

プロジェクトマッピング（projects.json）:

{
  "projects": [
    {
      "name": "My Site",
      "client": "Internal",
      "domain": "example.com",
      "gscSiteUrl": "sc-domain:example.com",
      "ga4Property": "properties/123456789",
      "notes": "Replace with the real GA4 property ID."
    }
  ]
}

5. 承認

npm run auth

スクリプトは 127.0.0.1:3000 でループバックリスナーを起動し、Google の URL を表示します。URL を開いて読み取り専用スコープを承認すると、トークンは GOOGLE_TOKEN_PATH に書き込まれます。

6. Claude Code に登録する

claude mcp add google-seo -- node /ABSOLUTE/PATH/TO/gsc-ga4-mcp/dist/index.js
claude mcp list

または、ツールを使い、プロジェクトに .mcp.json をチェックインします（.mcp.example.json を参照）。

{
  "mcpServers": {
    "google-seo": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gsc-ga4-mcp/dist/index.js"],
      "env": {
        "GOOGLE_AUTH_MODE": "oauth",
        "GOOGLE_OAUTH_CREDENTIALS_FILE": "/Users/YOUR_USER/.config/gsc-ga4-mcp/oauth-client.json",
        "GOOGLE_TOKEN_PATH": "/Users/YOUR_USER/.config/gsc-ga4-mcp/token.json",
        "PROJECTS_CONFIG": "/Users/YOUR_USER/.config/gsc-ga4-mcp/projects.json",
        "MCP_DEFAULT_GSC_SITE": "sc-domain:example.com",
        "MCP_DEFAULT_GA4_PROPERTY": "properties/123456789"
      }
    }
  }
}

パスやプロパティの初期値をリポジトリに置きたくない場合は、CLI 登録を使用します。

Claude Code での使い方

通常の日本語で質問してください。Claude がツールを選択します。

Use gsc_list_sites and ga4_list_properties. Give me a table of the GSC sites
and GA4 properties I can reach.

Analyse organic traffic for sc-domain:example.com over the last 90 days using
gsc_top_queries and gsc_top_pages.

Cross GSC and GA4 for example.com over the last 90 days. Find pages with high
impressions and low CTR, and rank the opportunities by likely impact.

Run seo_opportunity_report and group the output into quick wins, pages that
need a rewrite, and pages that miss search intent.

Inspect https://www.example.com/page/ with gsc_url_inspection and tell me
whether Google has it indexed.

運用上の注意

• .env、token.json、projects.json、サービスアカウントのキーはバージョン管理から除外してください。同梱の .gitignore にすでに含まれています。

• クライアントのアナリティクスデータは機密情報です。クライアントが承認していないツールへ完全な出力を貼り付けないでください。

• 契約が終了したら、トークンまたはサービスアカウントを失効させます。

• MAX_ROWS はレスポンスサイズを制限します。返答が扱いにくくなる場合は減らしてください。

トラブルシューティング

• Claude Code がツールを表示しない。 claude mcp list を実行し、Claude Code 内で /mcp を使動かします。

• OAuth トークンのエラー。 npm run auth を再実行し、GOOGLE_TOKEN_PATH が絶対パスであることを確認します。

• access_denied。 アプリがテスト中は、OAuth 同意画面で自分のメールアドレスをテストユーザーとして追加してください。

• GSC にドメインが表示されない。 認証情報にその正確なプロパティへのアクセス権が必要です。sc-domain:example.com と https://www.example.com/ は別物のプロパティです。

• GA4 プロパティが表示されない。 ユーザーまたはサービスアカウントに、アカウントまたはプロパティの少なくとも閲覧者（Viewer）権限が必要です。

• gsc_url_inspection が失敗する。 inspectionUrl が siteUrl の内部にある必要があり、URL プレフィックスプロパティは / で終わる必要があります。

• GA4 の指標が無効です。 公式の GA4 ディメンション名と指標名を使ってください。runReport はそれ以外を拒否します。

リファレンス

• Claude Code MCP ドキュメント

• Model Context Protocol

• Search Console API

• GA4 Data API

• Google Analytics Admin API

• Google OAuth scopes

ライセンス

MIT です。LICENSE を参照してください。