ads-mcp
Provides tools for managing and reporting on AdMob ad accounts, including listing accounts, apps, ad units, and generating network/mediation reports with full dimension, metric, filter, and sort control.
Provides tools for querying Huawei Petal Ads publisher reports, including daily earnings trends, per-app/placement breakdowns, and customizable group-by/filter/order/pagination reports.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ads-mcp How much did I earn from AdMob and Petal Ads yesterday?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 publisher accounts |
| AdMob | Account details (currency, timezone) |
| AdMob | List apps (paginated) |
| AdMob | List ad units (paginated) |
| AdMob | Network report with full dimension/metric/filter/sort control |
| AdMob | Mediation report (per ad-source performance) |
| Petal Ads | Publisher report with full group-by/filter/order/pagination control |
| Petal Ads | Daily earnings trend + totals for a date range |
| Petal Ads | Per-app (and per-placement) earnings breakdown |
| Both | Combined totals + daily breakdown across both networks |
| 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 .env2. Google AdMob
Open Google Cloud Console → select/create a project.
Enable the AdMob API in the API Library.
APIs & Services → Credentials → Create Credentials → OAuth client ID → Desktop app, then download the JSON.
Save it as
secrets/client_secret.json(or pointADMOB_CLIENT_SECRET_PATHin.envat it).Run the one-time authorization (opens a browser):
npm run auth:admobIf 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
Open HUAWEI Developers Console → HMS API Services → Credentials.
Create an OAuth 2.0 client ID (server type) with the Ads Kit / Publisher Service Reporting API enabled.
Put the credentials in
.env:
HUAWEI_CLIENT_ID=your_client_id
HUAWEI_CLIENT_SECRET=your_client_secretOr, if you keep them as a single combined key:
HUAWEI_ADS_API_KEY=client_id:client_secretNo 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 listRegister with an MCP client
Claude Code (CLI)
claude mcp add ads -- node /absolute/path/to/ads-mcp/dist/index.jsClaude 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 |
|
| Google OAuth Desktop-app client JSON |
|
| Cached authorized user token |
|
| Localhost port for the one-time OAuth flow |
| — | Huawei OAuth client (preferred) |
| — | Combined |
|
| Default report currency (CNY, USD, EUR) |
| Huawei production | Override for testing |
| Huawei production | Override for testing |
Security notes
secrets/and.envare gitignored — never commit credentials.The AdMob token file is written with
0600permissions.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.
Available Tools
11 toolsadmob_get_accountGet AdMob accountARead-onlyIdempotent
Get details (currency, timezone) for one AdMob publisher account.
Inputs: account_id (required).
admob_list_accountsList AdMob accountsARead-onlyIdempotent
List the Google AdMob publisher accounts available to the authorized user.
Inputs: no named parameters.
admob_list_ad_unitsList AdMob ad unitsARead-onlyIdempotent
List ad units under an AdMob account (paginated).
Inputs: page_size, account_id, page_token.
admob_list_appsList AdMob appsARead-onlyIdempotent
List apps registered under an AdMob account (paginated).
Inputs: page_size, account_id, page_token.
admob_mediation_reportAdMob mediation reportARead-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 reportARead-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 statusARead-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 overviewARead-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 performanceARead-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 reportARead-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 summaryARead-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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
Read-only Google Ads, Meta Ads and TikTok Ads performance, campaigns and creatives via OAuth.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
Access Google & Meta Ads data via AI. Analyse campaign performance in seconds.
Manage Google, Meta, TikTok, Snapchat and LinkedIn ads, plus GA4, Tag Manager and Search Console, by chat from Claude or ChatGPT. Spend increases need your confirmation first.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects 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.6MIT
- FlicenseNot gradedqualityDmaintenanceEnables 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-
- AlicenseAqualityDmaintenanceProvides 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.162MIT
- AlicenseBqualityAmaintenanceProvides AI agents with complete control over Google AdMob accounts, apps, ad units, mediation groups, A/B experiments, and performance reporting via the AdMob REST API.19MIT