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.

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

• AdMob API v1 (admob.googleapis.com/v1)
• Petal Ads Publisher Service Reporting API (ads.cloud.huawei.com/openapi/monetization/reports/v1/publisher)

Credits

• AdMob client and OAuth flow adapted from willhou/admob-mcp (MIT).
• Petal Ads integration follows the official HMS-Core/hms-ads-severdemo reference.

License

MIT — see LICENSE.