Skip to main content
Glama
ads-mcp

ads-mcp

by qalvinahmad

ads-mcp

A Model Context Protocol server that puts your mobile ad revenue in one conversational interface: Google AdMob and Huawei Petal Ads (Publisher Service), side by side.

Ask Claude things like:

"How much did I earn across AdMob and Petal Ads last week?"
"Which AdMob ad units are underperforming?"
"Break down my Petal Ads revenue by app"
"Compare yesterday's eCPM by country"

Tools

Tool

Network

Description

admob_list_accounts

AdMob

List publisher accounts

admob_get_account

AdMob

Account details (currency, timezone)

admob_list_apps

AdMob

List apps (paginated)

admob_list_ad_units

AdMob

List ad units (paginated)

admob_network_report

AdMob

Network report with full dimension/metric/filter/sort control

admob_mediation_report

AdMob

Mediation report (per ad-source performance)

petal_report

Petal Ads

Publisher report with full group-by/filter/order/pagination control

petal_revenue_summary

Petal Ads

Daily earnings trend + totals for a date range

petal_apps_performance

Petal Ads

Per-app (and per-placement) earnings breakdown

ads_revenue_overview

Both

Combined totals + daily breakdown across both networks

ads_auth_status

Both

Check which networks are configured/authorized

All tools are read-only — this server never mutates your ad accounts.

Related MCP server: Google Ads MCP Server

Prerequisites

  • Node.js 18+

  • For AdMob: a Google Cloud project with the AdMob API enabled and an OAuth 2.0 Desktop app client

  • For Petal Ads: a HUAWEI Developers OAuth client with the Publisher Service Reporting API (Ads Kit) enabled

Setup

1. Install and build

git clone https://github.com/qalvinahmad/ads-mcp.git
cd ads-mcp
npm install
npm run build
cp .env.example .env

2. Google AdMob

  1. Open Google Cloud Console → select/create a project.

  2. Enable the AdMob API in the API Library.

  3. APIs & Services → Credentials → Create Credentials → OAuth client ID → Desktop app, then download the JSON.

  4. Save it as secrets/client_secret.json (or point ADMOB_CLIENT_SECRET_PATH in .env at it).

  5. Run the one-time authorization (opens a browser):

npm run auth:admob

If your OAuth consent screen is in "Testing" status, add your Google account as a test user (otherwise you'll get an authorization error, and refresh tokens expire after 7 days).

3. Huawei Petal Ads

  1. Open HUAWEI Developers Console → HMS API Services → Credentials.

  2. Create an OAuth 2.0 client ID (server type) with the Ads Kit / Publisher Service Reporting API enabled.

  3. Put the credentials in .env:

HUAWEI_CLIENT_ID=your_client_id
HUAWEI_CLIENT_SECRET=your_client_secret

Or, if you keep them as a single combined key:

HUAWEI_ADS_API_KEY=client_id:client_secret

No browser flow is needed — Petal Ads uses OAuth client-credentials (server-to-server).

4. Verify

npm run doctor    # checks both networks; tests the Huawei token endpoint
npm run smoke     # boots the server and validates the MCP handshake + tool list

Register with an MCP client

Claude Code (CLI)

claude mcp add ads -- node /absolute/path/to/ads-mcp/dist/index.js

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ads": {
      "command": "node",
      "args": ["/absolute/path/to/ads-mcp/dist/index.js"]
    }
  }
}

Cursor / Windsurf / Cline

"ads": {
  "command": "node",
  "args": ["/absolute/path/to/ads-mcp/dist/index.js"]
}

Configuration is read from ads-mcp/.env automatically (the server resolves it relative to its own install directory, not the client's working directory).

Environment variables

Variable

Default

Description

ADMOB_CLIENT_SECRET_PATH

secrets/client_secret.json

Google OAuth Desktop-app client JSON

ADMOB_TOKEN_PATH

secrets/admob-token.json

Cached authorized user token

ADMOB_OAUTH_PORT

8089

Localhost port for the one-time OAuth flow

HUAWEI_CLIENT_ID / HUAWEI_CLIENT_SECRET

—

Huawei OAuth client (preferred)

HUAWEI_ADS_API_KEY

—

Combined client_id:client_secret fallback

HUAWEI_DEFAULT_CURRENCY

USD

Default report currency (CNY, USD, EUR)

HUAWEI_OAUTH_TOKEN_URL

Huawei production

Override for testing

HUAWEI_ADS_REPORT_URL

Huawei production

Override for testing

Security notes

  • secrets/ and .env are gitignored — never commit credentials.

  • The AdMob token file is written with 0600 permissions.

  • Huawei access tokens are cached in memory only.

  • All tools are read-only against both ad networks.

API references

Credits

License

MIT — see LICENSE.

Available Tools

11 tools
admob_get_accountGet AdMob accountA
Read-onlyIdempotent

Get details (currency, timezone) for one AdMob publisher account.

Inputs: account_id (required).

admob_list_accountsList AdMob accountsA
Read-onlyIdempotent

List the Google AdMob publisher accounts available to the authorized user.

Inputs: no named parameters.

admob_list_ad_unitsList AdMob ad unitsA
Read-onlyIdempotent

List ad units under an AdMob account (paginated).

Inputs: page_size, account_id, page_token.

admob_list_appsList AdMob appsA
Read-onlyIdempotent

List apps registered under an AdMob account (paginated).

Inputs: page_size, account_id, page_token.

admob_mediation_reportAdMob mediation reportA
Read-onlyIdempotent

Generate an AdMob Mediation report (per ad-source revenue and performance).

Dimensions: DATE, MONTH, WEEK, AD_SOURCE, AD_SOURCE_INSTANCE, AD_UNIT, APP, MEDIATION_GROUP, COUNTRY, FORMAT, PLATFORM, MOBILE_OS_VERSION, GMA_SDK_VERSION, APP_VERSION_NAME, SERVING_RESTRICTION. Only one time dimension (DATE/MONTH/WEEK) per request.

Metrics: AD_REQUESTS, CLICKS, ESTIMATED_EARNINGS, IMPRESSIONS, IMPRESSION_CTR, MATCHED_REQUESTS, MATCH_RATE, OBSERVED_ECPM. Monetary values are returned already divided from micros into currency units.

Inputs: start_date (required), raw, metrics, end_date, +7 more.

admob_network_reportAdMob network reportA
Read-onlyIdempotent

Generate an AdMob Network report (revenue, impressions, eCPM, ...).

Dimensions: DATE, MONTH, WEEK, AD_UNIT, APP, AD_TYPE, COUNTRY, FORMAT, PLATFORM, MOBILE_OS_VERSION, GMA_SDK_VERSION, APP_VERSION_NAME, SERVING_RESTRICTION. Only one time dimension (DATE/MONTH/WEEK) per request.

Metrics: AD_REQUESTS, CLICKS, ESTIMATED_EARNINGS, IMPRESSIONS, IMPRESSION_CTR, IMPRESSION_RPM, MATCHED_REQUESTS, MATCH_RATE, SHOW_RATE. Monetary values are returned already divided from micros into currency units.

Inputs: start_date (required), raw, metrics, end_date, +7 more.

ads_auth_statusAd network auth statusA
Read-onlyIdempotent

Check which ad networks are configured and authorized (AdMob OAuth token, Huawei credentials). Optionally performs a live Huawei token test. Never returns secret values.

Inputs: test_huawei_token.

ads_revenue_overviewCross-network revenue overviewA
Read-onlyIdempotent

Combined ad revenue overview across Google AdMob and Huawei Petal Ads for a date range (defaults to the last 7 days): totals per network, grand total, and a daily breakdown. Networks that are not configured are reported but do not block the other.

Inputs: days, currency, end_date, start_date, +2 more.

petal_apps_performancePetal Ads app performanceA
Read-onlyIdempotent

Per-app (optionally per-placement) Petal Ads earnings breakdown for a date range, ordered by earnings. Convenience wrapper around petal_report.

Inputs: currency, end_date, start_date, include_placements.

petal_reportPetal Ads reportA
Read-onlyIdempotent

Query the Huawei Petal Ads Publisher Service Reporting API with full control over grouping, filtering, ordering, and pagination. Returns monetization data (earnings, ad requests, impressions, clicks, match/show/click rates).

Inputs: start_date (required), raw, page, app_ids, +10 more.

petal_revenue_summaryPetal Ads revenue summaryA
Read-onlyIdempotent

Daily Petal Ads earnings trend plus totals for a date range (defaults to the last 7 days). Convenience wrapper around petal_report.

Inputs: days, currency, end_date, start_date.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool has a distinct purpose, with clear separation between admob and petal ads operations. The two report types (mediation and network) are differentiated, and convenience wrappers are explicitly noted.

    Naming Consistency5/5

    All tools use a consistent prefix (admob_, ads_, petal_) with snake_case verb_noun pattern. Verbs like get, list, report, and auth_status are uniformly applied, making the set predictable.

    Tool Count5/5

    11 tools cover the necessary operations for ad revenue reporting: account info, ad units, apps, two report types for admob, auth status, combined overview, and three petal tools. No excess or deficiency.

    Completeness5/5

    The tool set fully covers read-only access to ad monetization data from both AdMob and Huawei Petal Ads. Essential operations like listing, getting details, and generating reports are present, with no obvious gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects Claude to the Google AdMob API to provide a conversational interface for managing and analyzing ad revenue data. It enables users to generate custom network reports, track performance trends, and diagnose revenue fluctuations using natural language.
      6
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language access to Google Ads campaigns, accounts, and performance metrics via Claude, with tools for managing ad groups, keywords, budgets, and visualizing data.
      1
      -
    • A
      license
      A
      quality
      D
      maintenance
      Provides read access to campaign performance data from Google Ads, Meta Ads, and TikTok Ads via live API calls, enabling AI assistants to analyze and audit advertising campaigns.
      16
      2
      MIT