admob-mcp-server

AdMob MCP Server

英語 | 韓国語

AdMob アプリと収益について、AI アシスタントに自然な言葉で質問できます。

• 「過去 7 日間のアプリの収益を、国別に教えてください。」
• 「今月、最も eCPM が高かったメディエーションの広告ソースはどれですか？」
• 「バナー広告ユニットとリワード広告ユニットの RPM を比較してください。」
• 「アプリとその広告ユニットを一覧表示してください。」

これは、Google AdMob API 用の Model Context Protocol（MCP） サーバーです。
Claude Code、Claude Desktop、Cursor、Gemini CLI、その他 MCP 対応の AI クライアントで利用できます。

アーキテクチャ

flowchart LR
    C["MCP client<br/>Claude Code · Claude Desktop · Cursor · Gemini CLI"]

    subgraph S["admob-mcp-server — runs on your machine"]
        direction TB
        T["9 read-only tools in 5 toolsets<br/>accounts · apps · adunits · reports · mediation<br/>(filtered by --toolsets)"]
        A["Credential resolver<br/>env vars → token.json → gcloud ADC"]
        R["Report flattener<br/>chunk stream → rows · micros → currency"]
    end

    G["Google AdMob API<br/>v1beta"]

    C <-->|"MCP over stdio"| T
    T --> A
    A <-->|"OAuth 2.0 / HTTPS"| G
    G -.->|"report chunks"| R
    R -.-> T

認証情報と収益データは、お使いのマシンと Google の間だけでやり取りされます。間にサードパーティのサーバーはありません。

機能

• AdMob API が通常のアカウントに公開しているすべての機能 — アカウント、アプリ、広告ユニット、レポート、メディエーションにわたる 9 つのツール（書き込みツールがない理由）
• 読みやすいレポート — ストリーミング形式のレポート応答をシンプルな行テーブルに変換し、金額（マイクロ単位）を実際の通貨単位に換算します
• 設計上、読み取り専用 — サインインでは読み取りスコープのみを要求するため、このサーバーは AdMob アカウントの内容を変更できません
• ツールセット — 必要なツールグループのみを有効にできます（例：--toolsets reports,accounts）
• 3 つの認証方法 — コマンド 1 つでブラウザーからサインイン（npx admob-mcp-server auth）、環境変数の更新トークン、または gcloud Application Default Credentials
• 組み込みの分析プロンプトとレポート仕様のリファレンスリソース

概要とセットアップ

初回のセットアップには、約 10 分かかります。

必要条件

• Node.js 18 以降 — node --version で確認してください。インストールされていない場合は、nodejs.org からインストールしてください
• AdMob アカウントと、そのアカウントを所有する Google アカウント

セットアップ

パート 1 — Google Cloud のセットアップ

なぜ必要ですか？
AdMob API にはシンプルな API キーがありません。Google では、データにアクセスするすべてのプログラムを「OAuth アプリ」として登録する必要があります。
ここでは、自分だけが使う個人用のアプリを登録します。
無料で、課金設定も必要ありません。

1. Google Cloud プロジェクトを作成（または選択）する：console.cloud.google.com/projectcreate — 名前は何でもかまいません。既存のプロジェクトを再利用しても問題ありません。
2. AdMob API を有効にする：console.cloud.google.com/apis/library/admob.googleapis.com → 上部のバーでプロジェクトが選択されていることを確認 → 有効にする。
3. OAuth 同意画面を設定する：console.cloud.google.com/auth/overview — 初回アクセス時に短いウィザードが表示されます：
   • アプリ名：任意（例：admob-mcp）、サポート／連絡先メールアドレスには自分のメールアドレスを指定します
   • 対象ユーザー：外部
   • ウィザードを完了します — アプリを Google の審査に提出する必要はありません
   • 次に 対象ユーザー → テストユーザー → ユーザーを追加 に進み、AdMob アカウントを所有する Google アカウントを追加します
4. OAuth クライアントを作成する：console.cloud.google.com/apis/credentials → 認証情報を作成 → OAuth クライアント ID
   • アプリケーションの種類：デスクトップアプリ
   • 作成後、JSON をダウンロードをクリックします。このファイルをパート 2 で使用します

警告

同意画面がテストモードの間は、Google がサインインの有効期限を7 日後に設定するため、毎週サインインし直す必要があります。
これを避けるには、アプリを公開します（対象ユーザー → アプリを公開）。
自分で使用するために公開する場合、Google の審査は必要ありません。サインイン中に「未確認のアプリ」という警告が表示されますが、これは想定どおりです。

パート 2 — サインイン

ダウンロードした JSON ファイルをサーバーが参照する場所に移動してから、サインインコマンドを実行します：

mkdir -p ~/.admob-mcp
mv ~/Downloads/client_secret_*.json ~/.admob-mcp/oauth_client.json

npx admob-mcp-server auth

（Windows の場合は、エクスプローラーでファイルを C:\Users\<you>\.admob-mcp\oauth_client.json に移動してから、npx コマンドを実行します。）

ブラウザーが開きます。
AdMob アカウントを所有する Google アカウントを選び、アクセスを許可します。
**「Google はこのアプリを確認していません」**という警告が表示された場合、それはパート 1 で作成した自分のアプリです。「続行」をクリックします。
ターミナルに Setup complete と表示されると、サインイン情報が ~/.admob-mcp/token.json に保存され、以降は再利用されます。

サインインでは admob.readonly と admob.report のスコープが要求されます。どちらも読み取り専用です。

auth コマンドの動作：

sequenceDiagram
    autonumber
    participant T as Terminal
    participant S as admob-mcp-server
    participant B as Browser
    participant G as Google

    T->>S: npx admob-mcp-server auth
    S->>S: read ~/.admob-mcp/oauth_client.json
    S->>B: open consent URL (loopback redirect, random port)
    B->>G: sign in & allow scopes
    G-->>S: authorization code → refresh token
    S->>S: save ~/.admob-mcp/token.json (reused for every later call)

export GOOGLE_CLIENT_ID="....apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="..."
export GOOGLE_REFRESH_TOKEN="..."

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/admob.readonly,https://www.googleapis.com/auth/admob.report,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=path/to/oauth_client.json

認証情報の解決順序：環境変数 → token.json（auth から）→ ADC。

パート 3 — AI クライアントを接続する

以下からクライアントを選択してください。
MCP サーバーはクライアントの起動時に読み込まれるため、設定を追加した後はクライアントを再起動してください。

Claude Code

claude mcp add admob -- npx -y admob-mcp-server

claude mcp list で確認してください。admob: ... - ✔ Connected と表示されます。

Claude Desktop — Settings → Developer → Edit Config を開くと、claude_desktop_config.json（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）が開きます。次の設定を追加してください。

{
  "mcpServers": {
    "admob": {
      "command": "npx",
      "args": ["-y", "admob-mcp-server"]
    }
  }
}

アプリを再起動すると、チャット入力欄のツールメニューに admob のツールが表示されます。

Cursor — 同じ mcpServers ブロックを ~/.cursor/mcp.json に追加し、Settings → MCP で admob が有効になっていることを確認してください。

Gemini CLI — 同じ mcpServers ブロックを ~/.gemini/settings.json に追加し、CLI 内で /mcp を実行して確認してください。

ヒント

環境変数を使ってサインインした場合は、クライアントの env ブロックを通じて変数を渡してください（Claude Code：-- の前に --env KEY=value を繰り返し指定します。JSON 設定："args" の隣に "env": { ... } オブジェクトを追加します）。

試してみる

ツールを自分で呼び出す必要はありません。自然な言葉で尋ねるだけで、アシスタントが適切なツールを選びます。
まずは、次のように聞いてみましょう。

• 「先週、アプリの収益はいくらでしたか？」
• 「今月の収益を国別、アプリ別に内訳表示してください。」
• 「過去 30 日間で RPM が最も高かった広告フォーマットはどれですか？」
• 「メディエーションの状況はどうですか？観測された eCPM で広告ソースを比較してください。」
• 「アプリとその広告ユニットを一覧表示してください。」

ほとんどのクライアントでは、ツールを呼び出す前に許可を求めるため、承認なしに処理が実行されることはありません。

設定

設定はすべて任意です。デフォルト設定は単一の AdMob アカウントで使用できます。

環境変数

CLI フラグ

CLI フラグは環境変数より優先されます。
フラグはクライアント設定でコマンドの後に指定します。例：npx -y admob-mcp-server --toolsets reports

ツール

「ツール」とは、AI アシスタントがユーザーに代わって呼び出せる関数です。
ツールは5つのツールセットに分類されており、すべてデフォルトで有効です。

すべてのツールは読み取り専用で、admob.readonly / admob.report スコープが必要です。

書き込みツールがない理由

AdMob APIには書き込みメソッド（adUnits.create、apps.create、mediationGroups リソース全体）が用意されていますが、Googleはそれぞれにアクセス制限ありと指定しています。

このメソッドはアクセスが制限されています。403の権限拒否エラーが表示された場合は、アカウントマネージャーに連絡してアクセス権を取得してください。

通常のパブリッシャーアカウントでは、有効な admob.monetization トークンを持っていても、これらすべてのメソッドで PERMISSION_DENIED が返されます。また、同じ制限により、読み取り操作である mediationGroups.list と adUnitMappings.list もブロックされます。許可リストに登録されたアカウントなしではこれらのツールを使用できないため、提供していません。これらのツールを認識したアシスタントは実行を試みて失敗するためです。代わりに、AdMob コンソールで広告ユニットとメディエーショングループを作成してください。

accounts

apps

adunits

reports

すべてのレポートツールでは、startDate / endDate（YYYY-MM-DD）、metrics、およびオプションの dimensions、dimensionFilters、sortConditions、maxReportRows（デフォルトは1000）、currencyCode を指定します。
レスポンスはフラットなテーブル形式です。金額の指標はマイクロ単位から通貨単位に変換されます。

各レポートで有効なディメンションと指標は、MCP リソースとして公開されています（アシスタントが読み取れるリファレンスドキュメント）：admob://reference/network-report-spec、mediation-report-spec、campaign-report-spec。

メディエーション

メディエーショングループと広告ユニットのマッピングは対象外です。書き込みツールがない理由をご覧ください。

プロンプト

プロンプトは、すぐに使える分析リクエストです。
クライアントでは、スラッシュコマンドやプロンプト選択ツールとして表示されます（例：Claude Code で /top_performing_apps）。
いずれも省略可能な days 引数を受け取ります。

セキュリティとプライバシー

• サーバーはすべてお使いのコンピューター上で実行されます。
  データはお使いのマシンと Google の API 間でのみやり取りされ、サードパーティのサーバーを経由することはありません。
• 2 つのファイルがローカルに保存されます。どちらもユーザーアカウントのみが読み取り可能です：~/.admob-mcp/oauth_client.json（OAuth アプリ）と ~/.admob-mcp/token.json（サインイン情報）。
• サインアウトするには：~/.admob-mcp/token.json を削除し、必要に応じて myaccount.google.com/permissions でアプリのアクセス権を取り消してください。
• 変更できる項目はありません。サインインでは読み取り専用スコープのみが要求され、すべてのツールは読み取り専用です。

トラブルシューティング

インストールと接続

command not found: npx / spawn npx ENOENT

• 原因：Node.js がインストールされていないか、クライアントが Node.js を見つけられません。
• 対処法：nodejs.org から Node 18 以降をインストールし、クライアントを再起動してください。

クライアントにサーバーが表示されない

• 原因：MCP サーバーはクライアントの起動時に読み込まれるか、サーバーの起動に失敗しています。
• 対処法：まずクライアントを再起動してください。
  次に、MCP のステータスを確認し（Claude Code：claude mcp list、Gemini CLI：/mcp）、ターミナルで npx -y admob-mcp-server を実行してエラーが出ないことを確認してください。

サインインと認証

「使用可能な Google 認証情報が見つかりません」

• 原因：サインインがまだ設定されていません。
• 対処法：パート 2 — サインインの手順に従ってください。

invalid_grant / 「トークンの有効期限が切れているか、取り消されています」

• 原因：サインインの有効期限が切れています。
  同意画面が テスト モードの場合、これは 7 日ごとに発生します。
• 対処法：npx admob-mcp-server auth を再実行してください。
  再発を防ぐには、アプリを公開してください（Audience → Publish app）。

ブラウザーでのサインイン中に access_denied が発生する

• 原因：選択した Google アカウントが、同意画面のテストユーザーではありません。
• 対処法：Audience → Test users でそのアカウントを追加するか、アプリを公開してください。

「パブリッシャーを認証できませんでした」

• 原因：サインインに使用した Google アカウントに、有効な AdMob アカウントがありません。
• 対処法：npx admob-mcp-server auth を再実行し、アカウント選択画面で AdMob アカウントを所有するアカウントを選択してください。

API エラー

403 PERMISSION_DENIED

• 原因：AdMob API が有効になっていない、別の Google アカウントでサインインしている、またはスコープ変更前のトークンを使用しています。
• 対処法：次の項目を確認してください。
  1. OAuth クライアントと同じプロジェクトで AdMob API が有効になっている
  2. AdMob アカウントを所有するアカウントでサインインしている
  3. トークンに admob.readonly と admob.report が含まれている — 更新するには npx admob-mcp-server auth を再実行してください

429 RESOURCE_EXHAUSTED

• 原因：AdMob API のクォータに達しました（使用量の上限）。
• 対処法：時間をおいて再試行するか、日付範囲を狭める、ディメンションを減らすなど、リクエストを小さくしてください。

「複数の AdMob アカウントが見つかりました」

• 原因：Google のログインで複数のパブリッシャーアカウントにアクセスできます。
• 解決方法：ADMOB_ACCOUNT=pub-... を設定します（list_accounts で ID を確認できます）。

開発

git clone https://github.com/ParkSangGwon/admob-mcp-server.git
cd admob-mcp-server
npm install
npm test
npm run build

# debug with the MCP Inspector
npm run inspect

クライアントでローカルビルドを実行するには、npx の代わりにビルド済みのエントリーポイントを指定します：node /path/to/admob-mcp-server/dist/index.js。

リリース：v* タグをプッシュすると CI が実行され、来歴情報付きで npm に公開されます（.github/workflows/release.yml を参照）。

コントリビュート

イシューやプルリクエストを歓迎します。
大規模な変更の場合は、まずイシューを作成して方針について相談してください。
npm run lint、npm run format:check、npm test が成功することを確認してください。

ライセンス

MIT