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

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

Related MCP server: Google Ads MCP Server (Fork with Write Tools)

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

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.